The Inxmail Professional REST API provides programmatic access to Inxmail Professional, giving third parties the ability to extend Inxmail Professional by adding own functionality and services.

What’s new

REST API newsletter

If you would like to receive information about new Inxmail Professional REST API features by newsletter, subscribe here for free: Register

Version history

Version 4.8.68

Version 4.8.67

Version 4.8.66

Version 4.8.65

Version 4.8.64

Version 4.8.63

  • New: GET endpoint for server info. See Server Info

  • New: PUT endpoint for target groups. See Target groups

  • New: If-Modified-Since header in attribute request is applied to attributes without modification date. See Recipient Attributes

  • New: If-Modified-Since header in target-group request is applied to target-groups without modification date. See Target groups

  • New: If-Modified-Since header in text-modules request is applied to text-module without modification date. See Text modules

  • New: Post recipients without attributes field is invalid. See Recipients

Version 4.8.62

Version 4.8.61

Version 4.8.60

  • New: Delete Single Action Mailing. See Action-Mailings

  • New: GET ActionTrigger now includes the actions' sequence items. See Action Triggers

  • New: Delete Single Action Trigger. See Action Triggers

  • New: Filter recipient collection by attribute contains a specific string. See Recipients

Version 4.8.59

  • New: GET a mailing list by name using query params. See Mailing lists

  • New: Filter recipient collection by email that contains a specific string. See Recipients

Version 4.8.58

Version 4.8.57

Version 4.8.55

Version 4.8.54

Version 4.8.53

  • New: Add modificationDate and creationDate to text-modules response. See Text modules

  • New: Add modificationDate and creationDate to target-group response. See Target groups

  • New: Add modificationDate and creationDate to attribute response. See Recipient Attributes

Version 4.8.52

  • New: Add filter for last update to text-modules collection endpoint. See Text modules

  • New: Add filter for last update to target-groups collection endpoint. See Target groups

  • New: Add filter for last update to attribute collection endpoint. See Recipient Attributes

Version 4.8.51

  • New: REST Embed text module component recipient-attribute, in 'GET' request. See Textmodule/Embeddable relations

  • New: REST Embed text module component editor-content, in 'GET' request. See Textmodule/Embeddable relations

  • New: REST Embed text module component dynamic-parameters, in 'GET' & 'GET' collection request. See Textmodule/Embeddable relations

  • The former sections "Send a single mailing" and "Send a mailing / Continue Sending of an interrupted sending" that used to describe two different options for the same endpoint, have been merged and refined into a single section with better clarification what those options are, how to use them and what constraints apply. See Section Send a single mailing / send/continue a mass mailing

Version 4.8.50

Version 4.8.48

  • New: Create new endpoint for deleting a text module by id.See Text modules

  • New: Create new endpoint for updating a text module by id.See Text modules

  • New: Create new endpoint for retrieving all recipient-attributes of a list that are being used inside a given text module.See Text modules

Version 4.8.47

Version 4.8.46

Version 4.8.45

  • New: Add filters for mailings. It is possible to filter mailings by existing sending and mailing state. See Retrieve mailing collection

Version 4.8.44

Version 4.8.41

Version 4.8.40

Version 4.8.39

Version 4.8.38

Version 4.8.36

Version 4.8.35

Version 4.8.32

Version 4.8.31

Version 4.8.30

Version 4.8.29

Version 4.8.28

  • New: Retrieve unsubscription dates for specific lists when selecting recipients. See Recipients

  • New: Retrieve the schedule date of a regular mailing or collection. See Regular Mailings

Version 4.8.27

Version 4.8.26

Version 4.8.25

Version 4.8.24

Version 4.8.23

Version 4.8.22

  • New: Retrieve a specific target group or the target group collection. See Target groups

  • New: Endpoint to send test sendings. See Test Sendings

  • New: Retrieve a specific test mail group or the test mail group collection. See Test mail groups

  • New: Retrieve a specific text module or the text module collection. See Text modules

  • New: The recipient collection endpoint has new query parameters 'subscribedToAny' and 'unsubscribedFromAny'. See Retrieve recipients collection

  • Changed: A state of regular mailings was incorrectly documented as APPROVAL_GRANTED, now correctly documented as APPROVED. See: Regular Mailings

Version 4.8.19

Version 4.8.18

Version 4.8.17

Version 4.8.16

  • New: Retrieve a specific subscription mailing or the subscription mailings collection. See: Subscription Mailings

  • New: Retrieve a specific trigger mailing or the trigger mailings collection. See: Trigger-Mailings

  • New: Retrieve a specific action mailing or the action mailings collection. See: Action-Mailings

  • New: Retrieve a specific split test mailing or the split test mailings collection. See: Split-Test-Mailings

  • Fixed: Using the sentAfter filter in the regular-mailings endpoint could result in returning the same mailing multiple times in a single response if the "Send most recently sent mailing to new recipient" function was activated in the subscription manager of a list. See: Regular Mailings

Version 4.8.15

Version 4.8.14

Version 4.8.13

  • New: Retrieve bounces by the ids of the corresponding sendings, mailings or lists. See: Retrieve bounce collection

  • New: Add filter for mailings. It is possible to filter mailings by modification and creation date. See: Mailings

  • New: Retrieve clicks by the ids of the corresponding mailings or lists. See: Retrieve click collection

Version 4.8.12

Version 4.8.7

Version 4.8.4

  • New: It is possible to specify the id of the list into which a mailing should be copied to. See: Copy mailing

  • New: It is possible to specify a name for the copy of a mailing. See: Copy mailing

Version 4.8.3

  • New: Retrieve one regular mailing with embedded statistical data. See Retrieve single mailing

  • New: Retrieve a collection of mailings where regular mailings have statistical data embedded. See Retrieve mailing collection

  • New: It is possible to keep the approval state of a mailing when it is copied. See: Copy mailing

  • Info: A new section of this documentation describes the concept of embedding. See: Embedding

Version 4.8.2

  • New: Send an already approved mailing. See: Sendings

  • New: Continue an interrupted sending. See: Sendings

  • New: Retrieve regular mailings, which are ready to be sent. See: Retrieve mailing collection

  • Removed: Mailings with type SEQUENCE_MAILING are not supported anymore.

  • New: Copy operation for mailings. See: Copy mailing

Version 4.8.1

Version 4.8.0

Version 4.7.4

  • New: Retrieve all or a single test profile. See: Test profiles

  • New: Retrieve the rendered content of a mailing personalized with a test profile. See Mailing rendered content

  • New: Retrieve the tracking permission for a recipient in a given list. See Tracking permissions

  • New: Create a tracking permission for a recipient in a given list. See Create tracking permission

  • New: Delete the tracking permission for a recipient in a given list. See Delete tracking permission collection

  • New: Update recipients' email and attributes with a PATCH request. See: Patching a recipient

  • Fixed: Recipient imports now fully overwrites tracking permissions, as described in this documentation. Previously only present values were imported. See: Recipient Import

  • Fixed: If a the CSV file of a recipient import contained the tracking permission in the first column, those values were previously ignored. See: Recipient Import

Version 4.7.3

Version 4.7.2:

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.

General

This section describes general aspects of the Inxmail Professional REST API.

Base URL

All requests are scoped to a single Inxmail Professional customer. The name of the customer is specified as part of the base URL. All requests are performed via the secure HTTPS protocol.

Example URL

GET https://api.inxmail.com/{customer}/rest/v1
URL Parameters
customer

string (required) The name of the Inxmail Professional customer

Authentication

The Inxmail Professional REST API requires clients to authenticate themselves with credentials using HTTP Basic Authentication. The credentials consist of a client id and a secret, which can be supplied to the client software as username and password:

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

Important information about REST-Requests in web browsers

Please note:

Requests to the Inxmail Professional REST API should not be made with web browsers directly (E.g. opening a GET request URL).

Doing so bears the risk that the auth credentials could be leaked.

Please use appropriate REST clients instead (Browser-Extensions, Postman, curl, etc.) to interact with the API.

Types of resources

Resources are probably the most important concept of RESTful APIs. A resource is basically anything worth addressing and is closely related to the concept of classes in object oriented programming. Every resource is identified by a URL.

We make use of three different resource types:

  • A root resource

  • Primary resources

  • Collection resources

Note
 Terminology note: In the context of REST APIs, the term resource refers to an object which is addressed by a URL and lives on the server. There is no way to get a resource. When faced with a GET request on the URL addressing a resource, the server will return a representation of said resource, not the resource itself.
The root resource

The root resource is what you get when you request the API’s base URL. It is the entry point into the API, containing links to the subordinate resources which represent the different domain concepts of Inxmail Professional. We strongly recommend using these links to access other resources and refrain from bookmarking any URL other than the base URL. For more information on links, see section Hypermedia.

Primary resources

Primary resources identify a concrete object, like "the list with ID 3". They contain all relevant information on that object and may provide links to related resources.

Collection resources

Collection resources consist of a list of related resources, like "all mailing lists". To reduce the number of requests necessary to iterate over a collection, these items are embedded by default. When requesting a collection resource, you are presented with an embedded resource which contains a JSON array. For more information on embedded resources, see section Embedding.

The JSON array itself contains representations of the resources which are a part of this collection. The array may contain only a subset of the collection, depending on the total number of items in the collection. For more information on pagination and collection traversal, see section Pagination.

Each resource in a collection is presented in its default representation which is the same representation used when requesting the resource via its canonical URL (as a primary resource). In some cases this may have the effect of a differing structure between resources.

For example, the attributes collection may contain attribute resources with and without the maxLength field, depending on the type of the particular attribute.

Collection resources may provide additional filtering options which are applied using query parameters. The available filtering options are documented for each collection resource.

Some collection resources can be used to create new primary resources contained in the collection by sending a POST request to the collection. This is not supported by all collection resources, though.

Concept of operations

The RESTful API style is a great way to represent a domain model and allowing CRUD operations on all the available data, but is limited in representing very specific domain operations in an easy to use way.

To overcome this limitation this API additionally provides the ability to use commands in RPC style to trigger operations. To make it clear which parts of the API use the RPC style, all specific domain operations are located under the /operations/ endpoint.

Triggering operations using commands

Operation endpoints follow the following naming conventions: /operations/{resource-name}?command={command}. They are always triggered by invoking named commands using the POST method. Additional parameters for an operation can be provided in the request body.

The documentation for the available operations for a specific domain object is located in a separate operations section of each resource documentation.

Media Types

The Inxmail Professional REST API uses JSON as data format for requests and responses, in particular the HAL media type.

We make use of the following media types:

  • application/hal+json for common requests and responses.

  • application/problem+json for responses reporting error conditions, e.g. in case of input validation errors. For more information, see section Error response format.

  • application/merge-patch+json as the format used for PATCH requests, e.g. in the context of patching a recipient.

  • multipart/* is accepted for multipart requests that initiate the upload of files, e.g. in the context of a recipient import. Any multipart media type is accepted with multipart/form-data as the common choice and multipart/mixed being an arguable alternative.

  • text/csv for multipart request parts containing CSV data, e.g. in the context of a recipient import.

  • application/gzip for multipart request parts containing GZIP compressed data, e.g. in the context of a recipient import.

When making a request, we recommend setting the Accept header to application/hal+json,application/problem+json. While application/hal+json is sufficient to perform a successful request, there might be error conditions in which we use application/problem+json to convey details on the error. Do not set the Accept header to application/problem+json, as it will result in a 406 Not Acceptable error.

When doing a POST or PUT request, we recommend setting the Content-Type header to application/hal+json. If you experience technical problems using this content type, use application/json instead which is also accepted as a valid content type for request entities.

HAL is a hypermedia format which uses links to connect different resources and to provide ways for changing application state. For more information, see section Hypermedia.

Date/Time format and time zone

Date and time values are always exchanged in UTC+0 (also known as GMT or Zulu time) and ISO 8601 format. This is true for the values returned by this API as well as the values you provide when making requests.

Date/Time Format Example

Date with time

YYYY-MM-DD’T’HH:MM:SSZ

2016-02-04T10:30:12Z

Date only

YYYY-MM-DD

2016-02-04

Time only

HH:MM:SSZ

10:30:12Z

Remarks regarding time zones and daylight saving time (DST)

Terminology

Before diving into the specifics of Date/Time handling in this API, this section introduces the terminology used throughout the rest of this chapter. If you are already familiar with time zones, daylight saving time, UTC and related topics, you can skip this section.

Coordinated Universal Time (UTC)

The Coordinated Universal Time, or UTC for short, is the most widely used time standard used in the world. The standard itself is not relevant to understand this document. The important aspect is, that this API uses UTC to exchange date and time information.

UTC offset

UTC offsets are a means of communicating time across different time zones. The offset is appended to the string UTC, e.g. UTC+01:00 or UTC-09:30. For integer offsets, this form is often abbreviated to just the hour offset, e.g. UTC+1.

Time zone

You’re probably already familiar with the basic notion of time zones: The earth is divided into a number of more or less uniform time zones to coordinate local time with global time. Each time zone defines an offset with respect to UTC. In most cases, this value is an integer in the range from -12 to +14, with certain exceptions. Wikipedia provides a decent introduction into the topic.

Daylight Saving Time (DST)

Daylight saving time, or DST for short, is the practice of advancing clocks in the summer to postpone the sunset, while at the same time also postponing sunrise. It’s important to understand that DST is not used in all countries and countries may decide to stop using DST. The countries that do use DST, for the most part, advance clocks by exactly one hour. This is not the case for all countries, though.

ISO 8601

ISO 8601 specifies a standard format for communicating dates and times across different time zones. While the standard itself is not openly accessible, the relevant subset for this document is specified in RFC 3339.

General advice

As the handling of time zones and daylight saving time is a rather complex topic, we strongly recommend you use an existing library to work with the date/time information. ISO 8601 is supported by virtually any programming language, so there should be an appropriate library.

Date with time

If you only use this API to read and write values, you will never observe any time zone or daylight saving time (DST) offsets, as values have to be provided in UTC+0. The values you retrieve using this API will be the same ones you provided. This assumption is not correct, though, when you have to deal with values entered by Inxmail Professional users using the client application.

Date with time values entered using the client application are subject to time zone and daylight saving time (DST) offset adjustments. The determining factor is the time zone which is observed by the client application, both when writing values and when reading them. The DST offset is determined by two components:

  1. The DST offset of the time zone observed by the client application entering the value

  2. The date portion of the entered value

The time zone observed by the client determines:

  • if there is any DST offset at all

  • if so, what that offset is

  • at which date DST takes effect

  • at which date DST is suspended

Keep in mind that DST is not relevant in every time zone and the actual offset is not always one hour. Also, the date when DST takes effect varies.

For example, the time zone Europe/Berlin observes DST with an offset of one hour. Angola on the other hand does not observe DST while also using UTC+1 (West African Time). Lord Howe Island, Australia also observes DST but with an offset of half an hour. When DST is observed also varies, mainly due to different seasons depending on the hemisphere.

In conclusion: Whether a date with time value observes DST depends on whether DST is in effect at this specific date with regard to the time zone in use. The actual offset is also determined by the time zone. Whether the client was observing DST at the point at time of providing the value, is irrelevant.

Examples:

Using only this API

As stated before, if you only use this API to read and write values, you will never observe any offsets, as values have to be provided in UTC+0. However, be aware that date with time values entered using the Inxmail Professional client application are subject to adjustments.

The following examples clarify how a specific value entered using the client application will be rendered by this API.

Time zone Europe/Berlin

A date with time value of 01 February 2016 12:22:33 in the time zone Europe/Berlin will be rendered as 2016-02-01T11:22:33Z by this API, as the date portion is not observing DST in that time zone (UTC+1). A value of 01 August 2016 12:22:33 on the other hand will be rendered as 2016-08-01T10:22:33Z, as the date portion does observe DST (UTC+2).

Time zone Pacific/Honolulu

A date with time value of 01 February 2016 12:22:33 in the time zone Pacific/Honolulu will be rendered as 2016-02-01T22:22:33Z by this API. A value of 01 October 2016 12:22:33 will be rendered as 2016-10-01T22:22:33Z, as Hawaii does not observe DST.

Date only

Date only values are neither subject to time zone nor DST offset adjustments and are treated as-is by this API.

Time only

Time only values are also subject to time zone adjustments but do not consider DST offsets. This API will return time only values adjusted to time zone UTC+0.

Example:

The Inxmail Professional client application runs on a desktop machine in the time zone Europe/Berlin and is currently observing DST with an offset of one hour. If the user sets a time only attribute to 12:22:33, this API will return a value of 11:22:33Z, despite of the DST offset of the client host. The result is exactly the same if the desktop machine running the client does not observe DST.

Status Codes

The Inxmail Professional REST API uses a subset of the common HTTP Response Status Codes.

Table 4. Used Success response codes
HTTP Response Status Code Description

200 OK

RFC 7231

201 Created

RFC 7231

202 Accepted

RFC 7231

204 No Content

RFC 7231
Table 5. Used Client error codes
HTTP Response Status Code Description

400 Bad Request

RFC 7231

This is a typical Wide ranging error class.

401 Unauthorized

RFC 7235

403 Forbidden

RFC 7231

404 Not Found

RFC 7231

405 Method Not Allowed

RFC 7231

406 Not Acceptable

RFC 7231

See also supported Media types.

409 Conflict

RFC 7231

413 Payload Too Large

RFC 7231

415 Unsupported Media Type

RFC 7231

See also supported Media types.

429 Too many requests

RFC 6585
Table 6. Used Server error codes
HTTP Response Status Code Description

500 Internal Server Error

RFC 7231

HTTP Verbs

Verb Description

GET

Used for retrieving resources. Read operation which doesn’t change any data.

POST

Used for creating resources by sending data to the server.

PUT

Used for replacing existing resources by sending data to the server. No resource will be created if there is no current representation available.

DELETE

Used for deleting existing resources. A successful request will result in a response of 204 No Content without a body.

PATCH

Used for replacing parts of an existing resource by sending data to the server. No resource will be created if there is no current representation available.

Error States

There are two main reasons an API call might fail:

  1. Due to a client error

  2. Due to a server error

Client errors

A client error is indicated by a status code of the 4xx series, in particular 400 Bad Request and 404 Not found. The reasons for a client error might be:

  1. Failing to provide credentials for authentication

  2. Providing incorrect credentials for authentication

  3. Accessing a non existent resource

  4. Using malformed path or query parameters

  5. Submitting a malformed JSON document

  6. Submitting a JSON document using incorrect data types

  7. Submitting a JSON document with validation errors

  8. Manipulating a locked resource

  9. Sending too many requests

Providing no authentication credentials whatsoever will result in 401 Unauthorized. Providing incorrect authentication credentials will result in 403 Forbidden. Accessing a non existent resource will result in 404 Not found. Sending too many requests will result in 429 Too many requests. All other mentioned error conditions will result in 400 Bad Request.

Server errors

A server error is indicated by a status code of the 5xx series, in particular 500 Internal Server Error which states that the server was unable to fulfill the request due to an internal problem.

Error response format

All error responses contain a body which provides additional information on the error condition. The format used to convey this information is application/problem+json which is formally specified by RFC 7807. In this context the body is called a problem document.

We use three slightly different formats of responses with different levels of detail for each of the following error categories:

  1. Well defined error conditions, e.g. 404 Not Found

  2. Wide ranging error classes, e.g. 400 Bad Request

  3. Validation errors

  4. Rate limiting errors

Well defined error conditions

In the case of a well defined error condition, there is no need to provide any additional information. Therefore, the problem document is rather concise.

Example error response for a well defined error condition

HTTP/1.1 404 Not Found
Content-Type: application/problem+json
Content-Length: 53

{
  "type" : "about:blank",
  "title" : "Not Found"
}
Wide ranging error classes

More general error conditions, like the aforementioned 400 Bad Request, are explained in more detail to give you a clue what the actual error was.

Example error response for a problem from a wide ranging error class

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 275

{
  "type" : "type-mismatch",
  "title" : "a parameter had an incorrect type",
  "detail" : "provided value for parameter 'id' not supported.",
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/type-mismatch"
    }
  }
}

The type field contains a static ID of the error type which you can use to identify the issue at hand. The title field gives a short explanation of the error type while the detail field provides information on the actual error instance. The detail field is optional and may be omitted if there is no additional information to convey.

The response also contains a link to the documentation of the problem type where you can find more information on this type of error and suggestions on how to fix the issue.

The common problem types are documented in section Problem types.

Validation errors

The third class of problem is a validation error. This particular problem occurs if an entity provided in a POST or PUT request contains invalid data. In this case, the problem document contains an array with detailed information on the validation errors per field to aid you in constructing a valid entity.

Example error response for a validation error

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 462

{
  "type" : "validation-error",
  "title" : "invalid request parameters",
  "generalErrors" : [ "this object was invalid" ],
  "invalidFields" : [ {
    "field" : "fieldName",
    "problem" : "this field's value was invalid"
  }, {
    "field" : "anotherFieldName",
    "problem" : "this field's value also was invalid"
  } ],
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/validation-error"
    }
  }
}
Rate limiting errors

Sending too many request will result in a 429 Too many requests response. In that case, the Retry-After header is set, showing the time in seconds until the next request is possible. RFC 7231

More information about rate limiting can be found in section Rate Limiting.

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 45
Retry-After: 45

{
  "type" : "about:blank",
  "title" : "Too Many Requests"
}

Problem types

Duplicate resource
Problem type

duplicate-resource

Status code

409 Conflict

Reasons

Indicates that a resource with the given name or other identifier already exists. This might be the case if:

  1. you tried POSTing a resource with a name or identifier which is already in use

  2. you made a PUT request to rename a resource to a name which is already in use

Remedy

Choose a different name which is not yet taken.

Example problem document
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
Content-Length: 276

{
  "type" : "duplicate-resource",
  "title" : "resource already exists",
  "detail" : "A resource with the requested name already exists",
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/duplicate-resource"
    }
  }
}
Locked resource
Problem type

locked-resource

Status code

400 Bad Request

Reasons

Indicates that an operation on a resource failed because the resource is currently locked by another user. This might happen in response to a PUT or DELETE request.

Remedy

Wait for the resource to be unlocked. This might involve periodic retries or, if applicable, informing the user.

Example problem document
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 220

{
  "type" : "locked-resource",
  "title" : "the resource is locked by an other user",
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/locked-resource"
    }
  }
}
Invalid parameter value
Problem type

invalid-parameter-value

Status code

400 Bad Request

Reasons

Indicates that you provided an invalid value for a request parameter (i.e. query parameter). Common cases include:

  • Providing a non existent list as target list for a recipient import

  • Providing a list of the wrong type as target list for a recipient import

  • Providing a non existent test profile for rendering the content of a mailing

Remedy

Check all request parameters for validity. The documentation of the request parameters should contain information on the valid values.

In case you receive this problem document in response to an attempt to start a recipient import, check the listId parameter. The provided ID must correspond with an existing list of type STANDARD.

In case you receive this problem document in response to an attempt to render the content of a mailing, check the testProfileId parameter. The provided ID must correspond with an existing test profile.

Example problem document
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 278

{
  "type" : "invalid-parameter-value",
  "title" : "invalid parameter value",
  "detail" : "no object was found for the referenced id",
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/invalid-parameter-value"
    }
  }
}
Invalid request body
Problem type

invalid-request-body

Status code

400 Bad Request

Reasons

Indicates that you provided an invalid request body. This is usually the case if you provide invalid JSON as body for a POST or PUT request. The error might also indicate that you provided an invalid multipart request.

Remedy

Check your request body for validity. In case of a JSON body, you might try using a validation tool like JSONLint. In case this is a multipart request, check the HTTP body structure, especially the multipart boundary.

Example problem document
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 214

{
  "type" : "invalid-request-body",
  "title" : "unparsable request body",
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/invalid-request-body"
    }
  }
}
Missing parameter
Problem type

missing-parameter

Status code

400 Bad Request

Reasons

Indicates that a mandatory request parameter is missing.

Remedy

Check if you included all mandatory request parameters. The documentation should state which request parameters are mandatory for the request you are trying to make.

Example problem document
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 268

{
  "type" : "missing-parameter",
  "title" : "required parameter is missing",
  "detail" : "required parameter 'param' is missing",
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/missing-parameter"
    }
  }
}
Missing request part
Problem type

missing-request-part

Status code

400 Bad Request

Reasons

Indicates that a mandatory request part is missing. This should only occur in conjunction with multipart requests.

A common cause is a POST request triggering a recipient import which is a proper multipart request but lacks the mandatory file request part.

Remedy

Check if you included all mandatory request parts. The documentation should state which request parts are mandatory for the request you are trying to make.

If you encounter this error while triggering a recipient import, make sure you’ve included the file request part in your multipart request.

Example problem document
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 279

{
  "type" : "missing-request-part",
  "title" : "required request part is missing",
  "detail" : "required request part 'file' is missing",
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/missing-request-part"
    }
  }
}
Type mismatch
Problem type

type-mismatch

Status code

400 Bad Request

Reasons

Indicates that the value for a parameter has a different type than expected.

A common cause is a request with an id parameter for which the name of the resource was provided instead of the ID. The expected type in this case is integer while the actual type is string. This response also occurs when a request with a date parameter was provided, but the given date was not formatted properly.

Remedy

Check if you provided the correct type for all request parameters (i.e. query parameters). The error detail outlines which parameter caused the error.

Example problem document
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 275

{
  "type" : "type-mismatch",
  "title" : "a parameter had an incorrect type",
  "detail" : "provided value for parameter 'id' not supported.",
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/type-mismatch"
    }
  }
}
Unresolvable request
Problem type

unresolvable-request

Status code

400 Bad Request

Reasons

Indicates that the request could not be resolved.

Remedy

This is a very rare issue. If you should encounter this error, please contact us.

Example problem document
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 224

{
  "type" : "unresolvable-request",
  "title" : "the request could not be resolved",
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/unresolvable-request"
    }
  }
}
Validation error
Problem type

validation-error

Status code

400 Bad Request

Reasons

Indicates that the request body you provided did not pass validation. This issue can only be observed in conjunction with POST and PUT requests.

Remedy

Check all fields and the whole body of the request you provided for validity. The generalErrors and invalidFields fields in the problem document outlines which constraints did not validate and why. For additional information, also check the documentation which should contain information on the valid values for each field.

Example problem document
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 462

{
  "type" : "validation-error",
  "title" : "invalid request parameters",
  "generalErrors" : [ "this object was invalid" ],
  "invalidFields" : [ {
    "field" : "fieldName",
    "problem" : "this field's value was invalid"
  }, {
    "field" : "anotherFieldName",
    "problem" : "this field's value also was invalid"
  } ],
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/validation-error"
    }
  }
}
Duplicate Email
Problem type

duplicate-email

Status code

409 Conflict

Reasons

Indicates that a recipient related request could not be fulfilled because the email address of that recipient is already assigned to a different recipient. As email addresses are unique in Inxmail Professional, any email address can only be assigned to one recipient.

A common case is trying to change the email address of an existing recipient to an address already assigned to a different recipient.

Remedy

If you receive this problem as a result to a recipient update, the updated recipient might very well be the same as the existing recipient with the same email address. In that case, consider merging the two recipients into one.

If the recipient you are updating and the existing recipient are distinct recipients, you either have to assign unique email addresses to each of them or delete one of them.

There are various techniques to handle distinct recipients with the same email address. Please contact us for more information on how your specific use case can be implemented.

Example problem document
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
Content-Disposition: inline;filename=f.txt
Content-Length: 226

{
  "type" : "duplicate-email",
  "title" : "the specified email address is already in use",
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/duplicate-email"
    }
  }
}
Blacklisted
Problem type

blacklisted

Status code

400 Bad Request

Reasons

Indicates that a recipient related request could not be fulfilled because the email address of that recipient matches a blacklist entry.

A common case is trying to subscribe a recipient whose email address matches a blacklist entry.

Remedy

If possible, check whether the blacklist entry is valid. If it is, discard the request as this recipient must not enter the system. It might also be possible that the blacklist entry is not specific enough and falsely blocks this recipient. If that is the case, refine the blacklist entry to allow for this recipient to enter the system. This can only be done using the Inxmail Professional client application.

Example problem document
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 222

{
  "type" : "blacklisted",
  "title" : "the given email address matches a blacklist entry",
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/blacklisted"
    }
  }
}
Ambiguous Email
Problem type

ambiguous-email

Status code

409 Conflict

Reasons

Indicates that a recipient related request could not be fulfilled because the email address of that recipient does not uniquely identify a single recipient. This can only occur with specially configured Inxmail Professional systems.

Remedy

As that specific recipient can not be unambiguously identified by the email address, use the unique ID instead. To find the correct recipient, perform a request on the recipient collection with a filter on the email address. This will return the collection of all recipients with that address and may enable you to find the correct recipient if you have means of distinguishing them.

Example problem document
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
Content-Disposition: inline;filename=f.txt
Content-Length: 329

{
  "type" : "ambiguous-email",
  "title" : "the specified email address does not uniquely identify a single recipient",
  "detail" : "the address 'john.doe@example.com' identifies 2 recipients",
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/ambiguous-email"
    }
  }
}
Subscription error
Problem type

subscription-error

Status code

400 Bad Request

Reasons

Indicates that some aspect of a subscription request caused it to fail. The result and detail fields provide further information on the problem at hand.

Remedy

Check the result and detail fields of the problem document for further information on the problem at hand.

Example problem document
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 305

{
  "type" : "subscription-error",
  "title" : "subscription process failed",
  "detail" : "the given email address is not valid",
  "result" : "INVALID_ADDRESS_ERROR",
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/subscription-error"
    }
  }
}
Unsubscription error
Problem type

unsubscription-error

Status code

400 Bad Request

Reasons

Indicates that some aspect of an unsubscription request caused it to fail. The result and detail fields provide further information on the problem at hand. Common cases include:

  • Unsubscribing a recipient from a list she is already unsubscribed from.

  • Unsubscribing a recipient unknown to the system.

Remedy

Check the result and detail fields of the problem document for further information on the problem at hand. If the result field is DUPLICATE_UNSUBSCRIPTION, you can safely discard the request as the recipient is already unsubscribed from the list. If the result field is NOT_IN_SYSTEM_UNSUBSCRIPTION, you can also safely discard the request as the recipient is not in the system and therefore not subscribed to any list.

Example problem document
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 330

{
  "type" : "unsubscription-error",
  "title" : "unsubscription process failed",
  "detail" : "the recipient is already unsubscribed from that list",
  "result" : "DUPLICATE_UNSUBSCRIPTION",
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/unsubscription-error"
    }
  }
}
Mailing render error
Problem type

mailing-render-error

Status code

400 Bad Request

Reasons

Indicates that there were errors with the result that the mailing could not be rendered.

Remedy

Open the affected mailing in the Inxmail Professional client application to get more information about the cause. Use the Inxmail Professional client application to resolve the issues that caused the render error.

Notice the errors-field in the response to examine the details of the erros.

Table 7. Response fields
Path Type Description

errors

Array

The list of errors leading to this occuring exception.

errors[].description

String

The description of the error.

errors[].position

Object

The position in the source code where the error occurred.

errors[].errorCode

Number

1001

errors[].context

Array

string, another string
Example problem document
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 523

{
  "type" : "mailing-render-error",
  "title" : "rendering mailing failed",
  "detail" : "could not build mailing",
  "errors" : [ {
    "description" : "Text module 'foobar' not found",
    "position" : {
      "beginRow" : 3,
      "endRow" : 3,
      "beginColumn" : 5,
      "endColumn" : 9
    },
    "errorCode" : 1001,
    "context" : [ [ "string", "another string" ] ]
  } ],
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/mailing-render-error"
    }
  }
}
Unknown Recipient Attribute
Problem type

unknown-recipient-attribute

Status code

400 Bad Request

Reasons

Indicates that a specified recipient attribute does not exist.

A common case is trying to specify an attribute filter on the recipients collection with an invalid attribute name. This includes the use of non-user attributes (i.e. system attributes).

Remedy

If the specified attribute is required but does not currently exist, you might consider creating it. If the specified attribute is a non-user attribute, consider replacing it with a built-in filter. For example, to filter recipients by their last_modified date, simply use the lastModifiedSince parameter.

Example problem document
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 327

{
  "type" : "unknown-recipient-attribute",
  "title" : "the specified recipient attribute does not exist",
  "detail" : "the recipient attribute 'unknownAttribute' does not exist",
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/unknown-recipient-attribute"
    }
  }
}
Unparseable Recipient Attribute
Problem type

unparseable-recipient-attribute

Status code

400 Bad Request

Reasons

Indicates that a specified recipient attribute value could not be parsed.

Most likely, the data type of the specified recipient attribute is not compatible with the type of the specified value. For example, if the specified recipient attribute has the data type DATE_AND_TIME, you must provide an appropriately formatted datetime string, as described in the section Date/Time format and time zone.

Remedy

Provide a properly formatted value whose data type matches that of the specified recipient attribute. The expectedDataType field conveys the data type of the recipient attribute. If this data type is TEXT, the maxStringLength field contains the maximum number of characters the value may consist of.

Example problem document
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Disposition: inline;filename=f.txt
Content-Length: 408

{
  "type" : "unparseable-recipient-attribute",
  "title" : "a specified recipient attribute value can not be parsed",
  "detail" : "the value for recipient attribute 'salutation' could not be parsed",
  "expectedDataType" : "TEXT",
  "maxStringLength" : 10,
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/unparseable-recipient-attribute"
    }
  }
}
Unparseable Recipient Attribute Filter
Problem type

unparseable-recipient-attribute-filter

Status code

400 Bad Request

Reasons

Indicates that a specified recipient attribute filter could not be parsed.

Most likely, the data type of the specified recipient attribute is not compatible with the type of the specified matching value. For example, if the specified recipient attribute has the data type DATE_AND_TIME, you must provide an appropriately formatted datetime string, as described in the section Date/Time format and time zone.

Remedy

Provide a properly formatted matching value whose data type matches that of the specified recipient attribute. The expectedDataType field conveys the data type of the recipient attribute. If this data type is TEXT, the maxStringLength field contains the maximum number of characters the matching value may consist of.

Example problem document
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 429

{
  "type" : "unparseable-recipient-attribute-filter",
  "title" : "the specified recipient attribute filter can not be parsed",
  "detail" : "the filter on the recipient attribute 'salutation' could not be parsed",
  "expectedDataType" : "TEXT",
  "maxStringLength" : 10,
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/unparseable-recipient-attribute-filter"
    }
  }
}
Unsupported Recipient Attribute Filter
Problem type

unsupported-recipient-attribute-filter

Status code

400 Bad Request

Reasons

Indicates that a specified recipient attribute filter is not supported.

Most likely, the specified attribute has data type FLOATING_POINT_NUMBER or TIME_ONLY which are currently not supported for recipient attribute filters. In case of FLOATING_POINT_NUMBER attributes, this is due to the imprecise nature of floating point numbers which inhibits a meaningful comparison for equality.

Remedy

There is currently no way of filtering FLOATING_POINT_NUMBER or TIME_ONLY recipient attributes. If you have to filter by a recipient attribute with one of these data types, you will have to process the complete collection and apply filters manually.

We recommend to compare floating point numbers with a defined acceptable precision to avoid comparison errors due to varying precisions in the involved systems.

Example problem document
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Length: 419

{
  "type" : "unsupported-recipient-attribute-filter",
  "title" : "the specified recipient attribute filter is not supported for this operation",
  "detail" : "recipient attributes of type 'FLOATING_POINT_NUMBER' are currently not supported for this operation",
  "_links" : {
    "documentation" : {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/problems/unsupported-recipient-attribute-filter"
    }
  }
}

Hypermedia

Resources may have relations to other resources and in order to offer an easy way to navigate between them, we use HAL (Hypertext Application Language) to supply hyperlinks. HAL provides an easy way to navigate through the Inxmail Professional REST API by returning an array of links for every resource you acquire.

Hypermedia links are inside the "_links" node of a response. Each array contains at least a self link, pointing to the resource itself. This is helpful in cases where the resource is nested inside another resource where it is only represented partially. The self link provides a way to retrieve the full representation of the resource at its canonical URL.

It is strongly advised to use our generated links for navigation instead of creating your own links, so that API updates don’t break any existing code.

Example

When requesting a list of recipients, each recipient in the response contains a link to itself, making it easy to navigate to a specific recipient.

"recipients": [2]
    0:  {
        "id": 1
        "email": "recipient1@inxmail.invalid"
        "_links": {
            "self": {
                "href": "https://api.inxmail.com/customer/rest/v1/recipients/1"
            }
        }
    }
    1:  {
        "id": 2
        "email": "recipient2@inxmail.invalid"
        "_links": {
            "self": {
                "href": "https://api.inxmail.com/customer/rest/v1/recipients/2"
            }
        }
    }
}

Link relations

Link relations are used to provide semantics and addressability for links. For example, when you encounter the next relation, you can make the following assumptions:

  • The resource containing the link is a collection resource employing pagination

  • The target of the link is a the next page of the same collection resource

  • There actually is a non-empty next page

In addition, the relation provides a way of addressing the link to the next page. So, iterating through all pages of a collection becomes a matter of following the link addressed by the next relation until this relation is no longer present in the representation which means you have reached the final page.

In general, we try to use the link relations registered with the IANA whenever applicable. For a list of these link relations, see IANA link relations.

As these link relations don’t cover all aspects of the semantics this API provides, we created custom link relations which only apply in the context of this API.

Custom link relations

Each of the link relations listed below has a type and a description. The type specifies what the result of following the link will be. For example, the type Resource collection link relation specifies, that the result of following the link will be a collection of resources. The description provides further information.

lists
Type

Resource collection link relation

Description

The lists relation indicates that the corresponding link points to a collection of mailing lists.

list
Type

Resource link relation

Description

The list relation indicates that the corresponding link points to a specific mailing list. This indicates a generic relationship between the current resource and the mailing list referenced by the link.

mailings
Type

Resource collection link relation

Description

The mailings relation indicates that the corresponding link points to a collection of mailings.

mailing
Type

Resource link relation

Description

The mailing relation indicates that the corresponding link points to a specific mailing. This indicates a generic relationship between the current resource and the mailing referenced by the link.

renderedContent
Type

Resource link relation

Description

The renderedContent relation indicates that the corresponding link points to the rendered content of a specific mailing. This indicates a generic relationship between the current resource and the the rendered content of a specific mailing referenced by the link.

links
Type

Resource link relation

Description

The links relation indicates that the corresponding link points to the links collection of a specific mailing.

attributes
Type

Resource collection link relation

Description

The attributes relation indicates that the corresponding link points to a collection of recipient attributes.

recipients
Type

Resource collection link relation

Description

The recipients relation indicates that the corresponding link points to a collection of recipients.

recipient-imports
Type

Resource collection link relation

Description

The recipient-imports relation indicates that the corresponding link points to a collection of recipient imports. Please note, that the collection this relation refers to currently supports only POST requests.

files
Type

Resource collection link relation

Description

The files relation indicates that the corresponding link points to a collection of files. The meaning of this relation depends on the context it appears in. For example, in the context of recipient imports, the files relation refers to the source files which this import processes.

errors
Type

Resource collection link relation

Description

The errors relation indicates that the corresponding link points to a collection of import file errors.

subscription-events
Type

Resource collection link relation

Description

The subscription-events relation indicates that the corresponding link points to a collection of subscription events.

unsubscription-events
Type

Resource collection link relation

Description

The unsubscription-events relation indicates that the corresponding link points to a collection of unsubscription events.

sendings
Type

Resource collection link relation

Description

The sendings relation indicates that the corresponding link points to a collection of sendings.

clicks
Type

Resource collection click relation

Description

The clicks relation indicates that the corresponding link points to a collection of clicks.

web-beacon-hits
Type

Resource collection link relation

Description

The web-beacon-hits relation indicates that the corresponding link points to a collection of web-beacon-hits.

bounces
Type

Resource link relation

Description

The bounces relation indicates that the corresponding link points to a specific bounce. This indicates a generic relationship between the current resource and the bounce referenced by the link.

blacklist-entries
Type

Resource collection link relation

Description

The blacklist-entries relation indicates that the corresponding link points to a collection of blacklist entries.

upcoming
Type

Resource collection link relation

Description

Pagination link relation for a link to a page that does not exist yet. Used in collections on the current last page to point to a page becoming available once more data is entered into the system.

Prefix and Curies

You may have noticed, that the custom link relations defined above are not URIs, as would be required by RFC 5988, section 4.2. In order to reduce the length of the relations, we make use of the concept of curies.

In short, curies are used to establish a prefix for link relations which can be used to expand the relation name to the actual URI, similar to XML namespaces. In particular we make use of the curie support of the HAL media type, as specified in the HAL specification, section CURIEs.

Example

The following is an example of the status of a recipient import.

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 574

{
  "id" : 5,
  "successCount" : 38,
  "failCount" : 42,
  "state" : "PROCESSING",
  "triggerType" : null,
  "beginDate" : null,
  "endDate" : null,
  "files" : null,
  "targetListId" : null,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/5"
    },
    "inx:files" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/5/files"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Notice the custom relation inx:files in the links object. The inx prefix is used to expand the files relation to a URI, using the URL template provided in the curies array. To expand the relation, simply take the relation name (i.e. files) and replace {rel} in the href with the relation name. In this case, this would result in the following URL: https://apidocs.inxmail.com/xpro/rest/v1/relations/files

Embedding

In order to reduce the number of requests necessary to retrieve related data, embedding can be used to include other related resources, where available.

Resources that support embedding accept the embedded query parameter. This parameter takes a list of link relations which shall be included in the response. Which relations are supported is documented in the respective resource descriptions in a section "Embeddable relations".

The embedded resources will appear in the _embedded JSON node, each identified by their link relation. For collection resources, the _embedded node will appear inside each of the collection items.

Please note, that it is not guaranteed the _embedded node will be present. This depends on whether the embedded resource actually exists. For example: a request for a mailing with embedded sending statistics will only include them if the mailing has been sent.

Example request

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings/1?embedded=inx:response-statistics,inx:sending-statistics' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 2278

{
  "name" : "Name of the mailing",
  "id" : 1,
  "type" : "REGULAR_MAILING",
  "listId" : 42,
  "creationDate" : "2024-11-19T08:47:42Z",
  "subject" : "Subject of the mailing",
  "modificationDate" : "2024-11-19T08:47:42Z",
  "_embedded" : {
    "inx:response-statistics" : {
      "openingRecipients" : 1000,
      "botInteractions" : 0,
      "openingRate" : 0.1,
      "totalClicks" : 1000,
      "clickingRecipients" : 500,
      "uniqueClickRate" : 0.05,
      "ctor" : 0.5,
      "unsubscribeClicks" : 0,
      "listUnsubscribeClicks" : 0,
      "unsubscribeRate" : 0.0,
      "statisticsByLink" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/statistics/responses?mailingId=1&includeLinkData=false"
        }
      }
    },
    "inx:sending-statistics" : {
      "startDate" : "2024-11-19T08:47:42Z",
      "endDate" : "2024-11-19T08:47:42Z",
      "mailsPerHour" : 1000000.0,
      "recipientsCount" : 10000,
      "deliveredMailsCount" : 10000,
      "sentErrorCount" : 0,
      "bounceCount" : 0,
      "notSentMailsCount" : 0,
      "averageMailSize" : 102400.0,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/statistics/sendings?mailingId=1"
        }
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1?embedded=inx%3Aresponse-statistics&embedded=inx%3Asending-statistics"
    },
    "inx:renderedContent" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/renderedContent"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
    },
    "inx:sendings" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=1"
    },
    "inx:clicks" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=1"
    },
    "inx:web-beacon-hits" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=1"
    },
    "inx:links" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/links"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Embedding in the context of resource collections

Embedding is also used in resource collections to embed the resources contained in the collection. For more information, see section Collection resources.

Pagination

Pagination is a technique for breaking large record sets into smaller portions called pages. When requesting a collection resource, pagination is used in order to guarantee that the response doesn’t take too much time and is easy to handle. For example, getting all recipients could be a massive response which could take a lot of time. Also, the Internet is not a reliable network, therefore smaller responses increase the probability that a request is answered successfully.

Traversing with pagination

When requesting a collection resource, you are presented with navigation links that help you access all data within the requested collection. These links are included in each page of a collection resource and you should not calculate them yourself. Besides the usual self link, you will also find a link to the first page and a next page link. The first page link is omitted if you are on the first page already, the next page link is omitted once you reach the end of a collection resource. More information about hypermedia links can be found in the hypermedia section.

Limiting result size

By default, the result size is set to 1000 entries, which is the same as the maximum page size. You can change the page size by setting the pageSize parameter.

Note
 The default page size was increased from 100 to 1000 entries per page in order to reduce the number of requests needed to read all entries of a collection. Depending on the implementation, it might be necessary to accommodate to this new default or to explicitly request a page size of 100 entries.

Be aware that when you request a page size outside the allowed bounds, it is adjusted to a legal value. If you request a page size of less than 1, then the page size will be set to the default page size. If you request a page size higher than the maximum page size, then it is set to the maximum page size.

If you need a higher maximum page size, please contact us.

Cursor based pagination

Safely traversing the result set is a primary issue with stateless systems. The Inxmail Professional REST API uses cursor based pagination to ensure that you will never miss any data record. With cursor based pagination the next link in each collection resource is based on the ID of the last element on that page. When data is added to or deleted from the database, you still can continue to go through the pages of your paged result and receive all elements.

Live data

If you compare the Inxmail Professional SOAP API with the new REST API you will see a difference in behavior when looking up paged data. The SOAP API employs sessions and when requesting data, a snapshot is created on the initial request. With the Inxmail Professional REST API this is different as you will get live data. When requesting a collection resource, like all lists or all recipients, no snapshot is created at all.

Given a request for a collection resource, which is sorted ascending by ID, you are guaranteed to see all entries in the database using the provided next links, including entries created just moments ago. However, entries that are deleted before you reach their respective page are no longer available.

Also, be aware that while traversing a collection resource, the data on previous pages might already have changed. Therefore, if you return to the first page using the first link, this page is by no means guaranteed to resemble the state you observed when you first requested it. Records which were deleted in the mean time will not be included. Changes to these records will also be reflected. This behavior extends to the self link which will also reflect any changes performed on that resource in the mean time.

Available links for navigating the pages

To simplify the navigation through a collection resource a number of links are available. These links are attributed with a link relation to define the type of the link, or the relationship between the source and destination resource. The link relations used are a subset of the link relations defined by IANA and the custom upcoming link relation.

Keep in mind that you should always rely on these provided links. Don’t try to guess or construct your own URLs.

Long term data synchronization with the upcoming link

A typical use case is the synchronization of data, where you only want to get new objects in subsequent synchronizations. Over longer periods of time, there may be huge amounts of data and the practical way of synchronizing is to only look at new data.

To accommodate this, this API provides a special link on the last page of a collection resource. You can save this link and use it as a starting point for a future synchronization. The upcoming link leads to a page immediately following your last synchronized page of data. This page will be empty until data is entered into the system.

Please be aware, new data may not become available instantly upon being entered into the system, as it may be stored in write buffers for a while.

We strongly discourage synchronization based on timestamps for a number of reasons, including write buffers and unsynchronized clocks.

Please also mind, the upcoming link will only return a collection containing new objects, it will not return previously retrieved objects, even if they have been changed. If you want to capture all changes to all objects of a given type, just get the resource collection of this type.

If no new data has been entered into the system, following the upcoming link will return an empty collection.

Relation Description

self

The canonical link to this page.

first

The link relation for the first page of results.

next

The link relation for the immediate next page of results.

inx:upcoming

Links to a possible next page. This next page is only available once further data has been created in the system.

Parameters used for retrieving paginated results

Parameter Required Description

afterId

no

The largest existing item ID before the page, not to be included in the page

pageSize

no

The maximum number of elements in the page

Example response for paginated collection resource

The following example shows a collection resource, including links which can be used for traversing the result pages.

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1018

{
  "_embedded" : {
    "inx:examples" : [ {
      "id" : 13,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/examples/13"
        }
      }
    }, {
      "id" : 21,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/examples/21"
        }
      }
    }, {
      "id" : 25,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/examples/25"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/examples?afterId=5&pageSize=3"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/examples?afterId=25&pageSize=3"
    },
    "first" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/examples?afterId=0&pageSize=3"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Rate Limiting

Rate limiting is used to maintain the availability of the API and to guarantee acceptable response times.

Currently, the limit is set to 600 requests per minute. Please note that the rate limit can change in the future. Therefore, the calculation of the next possible request should always rely on the information in the headers. When receiving a response from the server, the X-RateLimit headers provide the needed information to calculate the point in time when the next request may be attempted.

Table 8. Rate limiting headers
Header Description

Retry-After

The time in seconds until the next reset, only shown when the limit is reached and an error response got returned. RFC 7231

X-RateLimit-Limit

The maximum number of requests per period

X-RateLimit-Remaining

The remaining number of requests in the current period

X-RateLimit-Reset

The time in seconds until the next reset

Server Info

The server info endpoint allows to retrieve information about the server. Currently, the server info endpoint provides only the information about the server version.

Retrieve server info

GET /customer/rest/v1/serverinfo HTTP/1.1
Host: api.inxmail.com

A GET request to the serverinfo endpoint returns the server info.

{
  "serverVersion" : "4.8.62.336",
}

Mailing lists

The concept of mailing lists used in Inxmail Professional is similar to regular mailing lists which you may be acquainted to as a developer. It is used to organize a subset of the recipients known to the system and send newsletters to these recipients.

There are four kinds of mailing lists:

  • Standard mailing lists

  • Dynamic mailing lists

  • The system mailing list

  • The administration mailing list

Standard mailing lists

This kind of mailing list is the equivalent of a regular mailing list. Membership is fairly static and can only be changed by either subscribing to the list (which will add a recipient to that list) or unsubscribing from the list.

Recipients who were unsubscribed from a list will no longer receive mailings sent via that list. They are, however, still known to that list. Inxmail Professional maintains a list of recipients who have been unsubscribed from a list along with a list of the subscribed members.

Dynamic mailing lists

In contrast to standard mailing lists, dynamic mailing lists employ a fluid membership which is determined by evaluating a target group each time the subscription status is required. A target group is used to segment recipients according to their attributes or reactions like clicks and openings.

Neither manual subscription nor unsubscription are supported for this type of mailing list, as the membership is solely bound to the target group this list is based on.

The system mailing list

The system mailing list is a special, virtual mailing list, which contains all recipients known to the system. It is used mainly to organize all recipients - especially those which are currently not assigned to any list - and to manage the system as a whole. There is only one system mailing list.

It is not possible to send mailings from the system mailing list.

The administration mailing list

The administration mailing list is another virtual mailing list. In contrast to the system mailing list, it contains no recipients at all and is solely used to manage certain properties of the system. There is only one administration mailing list. In the context of this API, it is rather safe to ignore this list.

Sender address and reply-to address

Static and dynamic mailings lists must have a sender address which is the email address used as the value for the sender header of a mail sent via that list. A list may have a reply-to address which is used as the value for the reply-to header. If a reply-to address is not set in the advanced list properties explicitly, the return value for the fields replyToAddress and replyToName will be null. However, when a mail is sent, the outgoing mail will still have a reply-to address. In such cases the sender address is used in the reply-to header.

The from header will always contain the address of the bounce mail account which is not accessible through this API. For more information, see RFC 5322, in particular section 3.6.

Note
 The address and name parts (e.g. senderAddress and senderName) are combined to form a mailbox address of the following form name <address>. In the context of RFC 5322 (section 3.4) name corresponds to display-name and address corresponds to addr-spec, thus forming an angle-addr.

Retrieve single mailing list

GET /lists/{id}

A GET request with a ID parameter will return the requested list.

Request structure

Table 9. /customer/rest/v1/lists/{id}
Parameter Description

id

The ID of the list

Response structure

Path Type Description

id

Number

The ID of the list

name

String

The name of the list

description

String

Some text describing the list

senderAddress

String

The email address of the sender associated to this list

senderName

String

The name of the sender associated to this list

replyToAddress

String

The email address which will be present in the reply-to header of every mailing sent from this list

replyToName

String

The display name associated with the replyToAddress

type

String

The type of the list. Possible values are [STANDARD, DYNAMIC, ADMIN, SYSTEM]

creationDate

String

The point in time when this list was created

modificationDate

String

The point in time when this list was modified

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/lists/5' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 970

{
  "id" : 5,
  "creationDate" : "1970-01-17T16:01:15Z",
  "modificationDate" : "1970-01-17T16:01:15Z",
  "name" : "sampleList",
  "description" : "sample description",
  "type" : "STANDARD",
  "senderAddress" : "john.doe@example.com",
  "senderName" : "John Doe",
  "replyToAddress" : "jane.doe@example.com",
  "replyToName" : "Jane Doe",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/5"
    },
    "inx:mailings" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings?listIds=5"
    },
    "inx:subscription-settings" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/5/subscription-settings"
    },
    "inx:unsubscription-settings" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/5/unsubscription-settings"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve mailing lists collection

GET /lists{?createdAfter,createdBefore,listNameContainsIgnoreCase,ids}

A GET request on the lists resource will return the first page of lists.

Response structure

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 4125

{
  "_embedded" : {
    "inx:lists" : [ {
      "id" : 1,
      "creationDate" : "1970-01-17T16:01:15Z",
      "modificationDate" : "1970-01-17T16:01:15Z",
      "name" : "system",
      "description" : "sample description",
      "type" : "SYSTEM",
      "senderAddress" : "john.doe@example.com",
      "senderName" : "John Doe",
      "replyToAddress" : "jane.doe@example.com",
      "replyToName" : "Jane Doe",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/1"
        },
        "inx:mailings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings?listIds=1"
        },
        "inx:subscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/1/subscription-settings"
        },
        "inx:unsubscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/1/unsubscription-settings"
        }
      }
    }, {
      "id" : 2,
      "creationDate" : "1970-01-17T16:01:15Z",
      "modificationDate" : "1970-01-17T16:01:15Z",
      "name" : "admin",
      "description" : "sample description",
      "type" : "ADMIN",
      "senderAddress" : "john.doe@example.com",
      "senderName" : "John Doe",
      "replyToAddress" : "jane.doe@example.com",
      "replyToName" : "Jane Doe",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/2"
        },
        "inx:mailings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings?listIds=2"
        },
        "inx:subscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/2/subscription-settings"
        },
        "inx:unsubscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/2/unsubscription-settings"
        }
      }
    }, {
      "id" : 3,
      "creationDate" : "1970-01-17T16:01:15Z",
      "modificationDate" : "1970-01-17T16:01:15Z",
      "name" : "sample standard list",
      "description" : "sample description",
      "type" : "STANDARD",
      "senderAddress" : "john.doe@example.com",
      "senderName" : "John Doe",
      "replyToAddress" : "jane.doe@example.com",
      "replyToName" : "Jane Doe",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        },
        "inx:mailings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings?listIds=3"
        },
        "inx:subscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3/subscription-settings"
        },
        "inx:unsubscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3/unsubscription-settings"
        }
      }
    }, {
      "id" : 4,
      "creationDate" : "1970-01-17T16:01:15Z",
      "modificationDate" : "1970-01-17T16:01:15Z",
      "name" : "sample dynamic list",
      "description" : "sample description",
      "type" : "DYNAMIC",
      "senderAddress" : "john.doe@example.com",
      "senderName" : "John Doe",
      "replyToAddress" : "jane.doe@example.com",
      "replyToName" : "Jane Doe",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/4"
        },
        "inx:mailings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings?listIds=4"
        },
        "inx:subscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/4/subscription-settings"
        },
        "inx:unsubscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/4/unsubscription-settings"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists?afterId=0&pageSize=6&createdAfter=2017-10-10T00%3A00%3A00Z&createdBefore=2019-10-10T00%3A00%3A00Z&listNameContainsIgnoreCase=system"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

See section pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/lists?createdAfter=2017-10-10T00:00:00Z&createdBefore=2019-10-10T00:00:00Z&listNameContainsIgnoreCase=system&ids=1,2,3,4' -i -X GET

HTTP Request Parameters

listNameContainsIgnoreCase

This request parameter allows retrieving lists with name filtering. Name of list should contain filter value.

Filtering is case-insensitive:

  • listNameContainsIgnoreCase=system

  • listNameContainsIgnoreCase=sYsTem

  • listNameContainsIgnoreCase=SyStem

  • listNameContainsIgnoreCase=SYSTEM

ids

This request parameter allows retrieving lists by ids. The parameter is optional. Multiple ids might be specified as:

  • ids=1,2,3,4

  • ids=1&ids=2&ids=3&id=4

listName

This request parameter allows retrieving lists with name filtering. Name of list should be filter value.

Filtering is case-sensitive:

  • listName=system → List.Name "system"

  • listName=sYsTem → List.Name "sYsTem"

  • listName=SyStem → List.Name "SyStem"

  • listName=SYSTEM → List.Name "SYSTEM"

Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 4125

{
  "_embedded" : {
    "inx:lists" : [ {
      "id" : 1,
      "creationDate" : "1970-01-17T16:01:15Z",
      "modificationDate" : "1970-01-17T16:01:15Z",
      "name" : "system",
      "description" : "sample description",
      "type" : "SYSTEM",
      "senderAddress" : "john.doe@example.com",
      "senderName" : "John Doe",
      "replyToAddress" : "jane.doe@example.com",
      "replyToName" : "Jane Doe",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/1"
        },
        "inx:mailings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings?listIds=1"
        },
        "inx:subscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/1/subscription-settings"
        },
        "inx:unsubscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/1/unsubscription-settings"
        }
      }
    }, {
      "id" : 2,
      "creationDate" : "1970-01-17T16:01:15Z",
      "modificationDate" : "1970-01-17T16:01:15Z",
      "name" : "admin",
      "description" : "sample description",
      "type" : "ADMIN",
      "senderAddress" : "john.doe@example.com",
      "senderName" : "John Doe",
      "replyToAddress" : "jane.doe@example.com",
      "replyToName" : "Jane Doe",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/2"
        },
        "inx:mailings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings?listIds=2"
        },
        "inx:subscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/2/subscription-settings"
        },
        "inx:unsubscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/2/unsubscription-settings"
        }
      }
    }, {
      "id" : 3,
      "creationDate" : "1970-01-17T16:01:15Z",
      "modificationDate" : "1970-01-17T16:01:15Z",
      "name" : "sample standard list",
      "description" : "sample description",
      "type" : "STANDARD",
      "senderAddress" : "john.doe@example.com",
      "senderName" : "John Doe",
      "replyToAddress" : "jane.doe@example.com",
      "replyToName" : "Jane Doe",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        },
        "inx:mailings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings?listIds=3"
        },
        "inx:subscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3/subscription-settings"
        },
        "inx:unsubscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3/unsubscription-settings"
        }
      }
    }, {
      "id" : 4,
      "creationDate" : "1970-01-17T16:01:15Z",
      "modificationDate" : "1970-01-17T16:01:15Z",
      "name" : "sample dynamic list",
      "description" : "sample description",
      "type" : "DYNAMIC",
      "senderAddress" : "john.doe@example.com",
      "senderName" : "John Doe",
      "replyToAddress" : "jane.doe@example.com",
      "replyToName" : "Jane Doe",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/4"
        },
        "inx:mailings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings?listIds=4"
        },
        "inx:subscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/4/subscription-settings"
        },
        "inx:unsubscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/4/unsubscription-settings"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists?afterId=0&pageSize=6&createdAfter=2017-10-10T00%3A00%3A00Z&createdBefore=2019-10-10T00%3A00%3A00Z&listNameContainsIgnoreCase=system"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Alternatively you can use the senderDomain parameter to filter lists by sender domain. Note that you can not use the other parameters in combination with senderDomain.

GET /lists{?senderDomain}

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/lists?senderDomain=example.com' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 4035

{
  "_embedded" : {
    "inx:lists" : [ {
      "id" : 1,
      "creationDate" : "1970-01-17T16:01:15Z",
      "modificationDate" : "1970-01-17T16:01:15Z",
      "name" : "system",
      "description" : "sample description",
      "type" : "SYSTEM",
      "senderAddress" : "john.doe@example.com",
      "senderName" : "John Doe",
      "replyToAddress" : "jane.doe@example.com",
      "replyToName" : "Jane Doe",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/1"
        },
        "inx:mailings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings?listIds=1"
        },
        "inx:subscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/1/subscription-settings"
        },
        "inx:unsubscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/1/unsubscription-settings"
        }
      }
    }, {
      "id" : 2,
      "creationDate" : "1970-01-17T16:01:15Z",
      "modificationDate" : "1970-01-17T16:01:15Z",
      "name" : "admin",
      "description" : "sample description",
      "type" : "ADMIN",
      "senderAddress" : "john.doe@example.com",
      "senderName" : "John Doe",
      "replyToAddress" : "jane.doe@example.com",
      "replyToName" : "Jane Doe",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/2"
        },
        "inx:mailings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings?listIds=2"
        },
        "inx:subscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/2/subscription-settings"
        },
        "inx:unsubscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/2/unsubscription-settings"
        }
      }
    }, {
      "id" : 3,
      "creationDate" : "1970-01-17T16:01:15Z",
      "modificationDate" : "1970-01-17T16:01:15Z",
      "name" : "sample standard list",
      "description" : "sample description",
      "type" : "STANDARD",
      "senderAddress" : "john.doe@example.com",
      "senderName" : "John Doe",
      "replyToAddress" : "jane.doe@example.com",
      "replyToName" : "Jane Doe",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        },
        "inx:mailings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings?listIds=3"
        },
        "inx:subscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3/subscription-settings"
        },
        "inx:unsubscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3/unsubscription-settings"
        }
      }
    }, {
      "id" : 4,
      "creationDate" : "1970-01-17T16:01:15Z",
      "modificationDate" : "1970-01-17T16:01:15Z",
      "name" : "sample dynamic list",
      "description" : "sample description",
      "type" : "DYNAMIC",
      "senderAddress" : "john.doe@example.com",
      "senderName" : "John Doe",
      "replyToAddress" : "jane.doe@example.com",
      "replyToName" : "Jane Doe",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/4"
        },
        "inx:mailings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings?listIds=4"
        },
        "inx:subscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/4/subscription-settings"
        },
        "inx:unsubscription-settings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/4/unsubscription-settings"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists?afterId=0&pageSize=6&listName=example.com"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Create mailing list

POST /lists

A POST request with the following payload structure will create a new list. Violations of the constraints will lead to validation errors.

Payload structure

Path Type Description Constraints

name

String

The name of the new list

  • Must not be null

  • Must not contain padding whitespace characters

  • Size must be between 1 and 255 inclusive

type

String

The type of the new list

  • Must be STANDARD

  • Must not be null

senderAddress

String

The email address of the sender of the new list

  • Must be a valid email address

  • Must not be null

senderName

String

The name of the sender of the new list

  • Must not contain padding whitespace characters

replyToAddress

String

The email address which will be present in the reply-to header of every mailing sent from this list

  • Must be a valid email address

replyToName

String

The display name associated with the replyToAddress

  • Must not contain padding whitespace characters

description

String

The description of the new list

  • Size must be between 0 and 255 inclusive

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/lists/' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "name" : "sampleList",
  "type" : "STANDARD",
  "senderAddress" : "john.doe@example.com",
  "senderName" : "John Doe",
  "replyToAddress" : "jane.doe@example.com",
  "replyToName" : "Jane Doe",
  "description" : "sample description"
}'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/lists/5
Content-Type: application/hal+json
Content-Length: 429

{
  "id" : 5,
  "creationDate" : "1970-01-17T16:01:15Z",
  "modificationDate" : null,
  "name" : "sampleList",
  "description" : "sample description",
  "type" : "STANDARD",
  "senderAddress" : "john.doe@example.com",
  "senderName" : "John Doe",
  "replyToAddress" : "jane.doe@example.com",
  "replyToName" : "Jane Doe",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/5"
    }
  }
}

Edit mailing list

PUT /lists/{id}

A PUT request with the following payload structure will replace an existing list. Violations of the constraints will lead to validation errors.

Payload structure

Path Type Description Constraints

name

String

The new name of the list

  • Must not be null

  • Must not contain padding whitespace characters

  • Size must be between 1 and 255 inclusive

senderAddress

String

The new email address of the sender of the list

  • Must be a valid email address

  • Must not be null

senderName

String

The new name of the sender of the list

  • Must not contain padding whitespace characters

replyToAddress

String

The email address which will be present in the reply-to header of every mailing sent from this list

  • Must be a valid email address

replyToName

String

The display name associated with the replyToAddress

  • Must not contain padding whitespace characters

description

String

The new description of the list

  • Size must be between 0 and 255 inclusive

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/lists/5' -i -X PUT \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "name" : "sampleList",
  "senderAddress" : "john.doe@example.com",
  "senderName" : "John Doe",
  "replyToAddress" : "jane.doe@example.com",
  "replyToName" : "Jane Doe",
  "description" : "sample description"
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 429

{
  "id" : 5,
  "creationDate" : "1970-01-17T16:01:15Z",
  "modificationDate" : null,
  "name" : "sampleList",
  "description" : "sample description",
  "type" : "STANDARD",
  "senderAddress" : "john.doe@example.com",
  "senderName" : "John Doe",
  "replyToAddress" : "jane.doe@example.com",
  "replyToName" : "Jane Doe",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/5"
    }
  }
}

Delete mailing list

DELETE /lists/{id}

A DELETE request will remove a mailing list and all the objects depending on it (e.g. all mailings in that list).

Be aware that a list can not be deleted if it is locked by another user (e.g. an Inxmail Professional user editing a mailing in that list via the desktop client application). A DELETE request on a locked mailing list will trigger a locked-resource error.

Also, it is impossible to delete the system and administration lists. A DELETE request on one of these lists will result in an invalid-parameter-value error.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/lists/5' -i -X DELETE
Response
HTTP/1.1 204 No Content

Retrieve recipient count of a mailing list

GET /lists/{id}/count

A GET request with ID parameter will return the number of recipients subscribed to the requested list. The number of recipients will be calculated live and 'LastCalculatedAt' date is set to request time in case requested list is global or standard list. Otherwise this number is only recalculated infrequently (because of performance considerations). The returned resource will also tell you when the count has been last updated. At the moment there is no way for the user to force an update of the count, the server will decide on the update frequency.

Request structure

Table 10. /customer/rest/v1/lists/{id}/count
Parameter Description

id

The ID of the list. To receive the count of all recipients use the system list with id = 1.

Response structure

Path Type Description

id

Number

The ID of the list

count

Number

The number of recipients subscribed to the list.

lastCalculatedAt

String

The calculation date of the count. The value of the count is taken directly from database in case list is global or standard. Otherwise the value of the count is cached and stored in the database.

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/lists/5/count' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 189

{
  "id" : 5,
  "count" : 5,
  "lastCalculatedAt" : "2024-11-19T08:47:29Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/5/count"
    }
  }
}

List settings

Mailing lists have various settings that affect the behavior of the list itself and of the associated objects (e.g. mailings). These settings can be changed using this API.

Available settings for the system list

Currently, this API supports only a limited subset of the list settings for the system list. The available settings for the system lists are:

Setting name Default value Description

floatDecimalPlaces

The number of decimal places to use for numbers

thousandsSeperator

If set, a thousands separator will be used in numbers

formatLocale

The locale used for formatting. E.g. "de" for German, "en" for English.

charset

The charset encoding

sendrate

The maximum send rate. If 0 is set, unlimeted send rate is used.

recaptchaConfig

The configuration of google recaptcha containing a list of valid domains used for google recaptcha.

Available settings for standard lists

Currently, this API supports only a limited subset of the list settings provided by Inxmail Professional. The available settings for standard lists are:

Setting name Default value Description

trackingPermissionDetachedFromMembership

"false"

If this setting is "false" (the default), tracking permissions are revoked when a recipient is removed from a list. Furthermore, tracking permissions can not be changed for recipients who are not subscribed to the affected list.

If this setting is "true", tracking permissions are retained when a recipient is removed from a list and the recipient can change the tracking permission for a list she is not a member of. Be aware though, that the tracking permission will still be revoked when a recipient is unsubcribed from a list instead of being removed from the list.

senderAddress

(mandatory)

The sender address for mailings sent to this list. If not set, the sender address is used.

replyToAddress

(sender address)

The reply to address for mailings sent to this list. If not set, the sender address is used.

formatLocale

The locale to use for formatting numbers and dates. E.g. "de" for German, "en" for English.

floatDecimalPlaces

The number of decimal places to use for numbers

thousandsSeperator

Defines, if the thousands separator should be used

charset

The charset encoding

sendrate

The maximum send rate. If 0 is set, unlimeted send rate is used.

Querying list setting

A GET request with a list ID parameter will return all settings for the list. Use list id "1" for the system list.

GET /lists/{id}/settings

The following response will be returned:

{
  "senderAddress" : {
    "setValue" : "test@inxserver.com",
    "effectiveValue" : "test@inxserver.com"
  },
  "replyToAddress" : {
    "setValue" : "test@inxserver.com",
    "effectiveValue" : "test@inxserver.com"
  },
  "charset" : {
    "setValue" : null,
    "effectiveValue" : "UTF-8"
  },
  "thousandsSeparator" : {
    "setValue" : "true",
    "effectiveValue" : "true"
  },
  "trackingPermissionDetachedFromMembership" : {
    "setValue" : "true",
    "effectiveValue" : "true"
  },
  "formatLocale" : {
    "setValue" : "de",
    "effectiveValue" : "de"
  },
  "sendrate" : {
    "setValue" : null,
    "effectiveValue" : "0"
  },
  "floatDecimalPlaces" : {
    "setValue" : "2",
    "effectiveValue" : "2"
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/5/settings"
    }
  }
}

Changing a list setting

PATCH /lists/5/settings

A PATCH request with the following payload structure will change the value of a list setting. Violations of the constraints will lead to validation errors.

Request structure

PATCH /customer/rest/v1/lists/5/settings HTTP/1.1
Content-Type: application/merge-patch+json
Content-Length: 456
Host: api.inxmail.com

{
  "charset" : {
    "setValue" : "UTF-8"
  },
  "sendrate" : {
    "setValue" : "3600"
  },
  "formatLocale" : {
    "setValue" : "en"
  },
  "floatDecimalPlaces" : {
    "setValue" : "2"
  },
  "thousandsSeparator" : {
    "setValue" : "true"
  },
  "trackingPermissionDetachedFromMembership" : {
    "setValue" : "true"
  },
  "senderAddress" : {
    "setValue" : "test@example.com"
  },
  "replyToAddress" : {
    "setValue" : "test@example.com"
  }
}

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/lists/5/settings' -i -X PATCH \
    -H 'Content-Type: application/merge-patch+json' \
    -d '{
  "charset" : {
    "setValue" : "UTF-8"
  },
  "sendrate" : {
    "setValue" : "3600"
  },
  "formatLocale" : {
    "setValue" : "en"
  },
  "floatDecimalPlaces" : {
    "setValue" : "2"
  },
  "thousandsSeparator" : {
    "setValue" : "true"
  },
  "trackingPermissionDetachedFromMembership" : {
    "setValue" : "true"
  },
  "senderAddress" : {
    "setValue" : "test@example.com"
  },
  "replyToAddress" : {
    "setValue" : "test@example.com"
  }
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 563

{
  "trackingPermissionDetachedFromMembership" : {
    "setValue" : "true"
  },
  "charset" : {
    "setValue" : "UTF-8"
  },
  "sendrate" : {
    "setValue" : "3600"
  },
  "floatDecimalPlaces" : {
    "setValue" : "2"
  },
  "thousandsSeparator" : {
    "setValue" : "true"
  },
  "formatLocale" : {
    "setValue" : "en"
  },
  "senderAddress" : {
    "setValue" : "test@example.com"
  },
  "replyToAddress" : {
    "setValue" : "test@example.com"
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/5"
    }
  }
}

Subscription Settings

A Subscription Setting holds the configuration for the subscriptions. Each Subscription Setting belongs to a list.

Retrieve single subscription setting

GET /lists/{listId}/subscription-settings

Request Structure

Table 11. /customer/rest/v1/lists/{listId}/subscription-settings
Parameter Description

listId

The ID of the list to get the subscription-settings from.

Response structure

Path Type Description

subscriptionType

Number

The Subscription Type: 10 if confirmed opt-in, 11 if double opt-in

sendWelcomeMessage

Boolean

if a welcome message should be send

welcomeMailingId

Number

The id of the welcomeMailing

verificationTimeoutMailingId

Number

The id of the time out mailing

verificationMailingId

Number

The id of the verification mailing

sendDoiVerificationTimeoutMessage

Boolean

If double opt-in timeout mailings should be send

doiConfirmationDuration

Number

Number of days in which double opt-in must be confirmed

doiLandingPage

String

The URL of the double opt-in landing page

doiTimeoutLandingPage

String

The URL of the double opt-in timeout page

sendRecentMail

Boolean

If recent mails should be send to new recipients

overwriteExistingMember

Boolean

If existing recipients should be overriden

subscriptionCommand

String

The Subscription Command

notifySubscriptionRequest

Boolean

If notifications should be send at unconfirmed subscription

notifySubscriptionVerification

Boolean

If notifications should be send at confirmed subscription

notifyAddress

String

The email address ss to send notifications to

_links

Object

Links to other resources

Example

Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 948

{
  "doiLandingPage" : "https://example.com/landing-page",
  "subscriptionType" : 10,
  "sendWelcomeMessage" : false,
  "verificationMailingId" : 0,
  "welcomeMailingId" : 8,
  "sendDoiVerificationTimeoutMessage" : false,
  "verificationTimeoutMailingId" : 13,
  "doiConfirmationDuration" : 30,
  "doiTimeoutLandingPage" : "https://example.com/time-out",
  "sendRecentMail" : true,
  "overwriteExistingMember" : false,
  "subscriptionCommand" : "subscribe",
  "notifySubscriptionRequest" : true,
  "notifySubscriptionVerification" : true,
  "notifyAddress" : "ex@example.com",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/1/subscription-settings"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/1"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Edit subscription setting

A PUT request with the following payload structure will replace the subscription-settings for an existing list.

  • PUT request on list, which are not of type standard will return a 400 response.

  • PUT request with none existing mailing id ("welcomeMailingId" or "verificationMailingId" or "verificationTimeoutMailingId") will return a 400 response.

  • PUT request with mailing id ("welcomeMailingId" or "verificationMailingId" or "verificationTimeoutMailingId") that belongs to different list return a 400 response.

  • Put request on non-existing lists will return 404.

Payload structure

PUT /customer/rest/v1/lists/1/subscription-settings HTTP/1.1
Content-Type: application/hal+json
Content-Length: 589
Host: api.inxmail.com

{
  "notifySubscriptionRequest" : true,
  "sendDoiVerificationTimeoutMessage" : false,
  "subscriptionType" : 10,
  "doiConfirmationDuration" : 30,
  "verificationMailingId" : 0,
  "overwriteExistingMember" : false,
  "sendWelcomeMessage" : false,
  "sendRecentMail" : true,
  "doiTimeoutLandingPage" : "https://example.com/time-out",
  "doiLandingPage" : "https://example.com/landing-page",
  "welcomeMailingId" : 8,
  "id" : 0,
  "subscriptionCommand" : "subscribe",
  "notifySubscriptionVerification" : true,
  "verificationTimeoutMailingId" : 13,
  "notifyAddress" : "ex@example.com"
}

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/lists/1/subscription-settings' -i -X PUT \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "notifySubscriptionRequest" : true,
  "sendDoiVerificationTimeoutMessage" : false,
  "subscriptionType" : 10,
  "doiConfirmationDuration" : 30,
  "verificationMailingId" : 0,
  "overwriteExistingMember" : false,
  "sendWelcomeMessage" : false,
  "sendRecentMail" : true,
  "doiTimeoutLandingPage" : "https://example.com/time-out",
  "doiLandingPage" : "https://example.com/landing-page",
  "welcomeMailingId" : 8,
  "id" : 0,
  "subscriptionCommand" : "subscribe",
  "notifySubscriptionVerification" : true,
  "verificationTimeoutMailingId" : 13,
  "notifyAddress" : "ex@example.com"
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 706

{
  "doiLandingPage" : "https://example.com/landing-page",
  "subscriptionType" : 10,
  "sendWelcomeMessage" : false,
  "verificationMailingId" : 0,
  "welcomeMailingId" : 8,
  "sendDoiVerificationTimeoutMessage" : false,
  "verificationTimeoutMailingId" : 13,
  "doiConfirmationDuration" : 30,
  "doiTimeoutLandingPage" : "https://example.com/time-out",
  "sendRecentMail" : true,
  "overwriteExistingMember" : false,
  "subscriptionCommand" : "subscribe",
  "notifySubscriptionRequest" : true,
  "notifySubscriptionVerification" : true,
  "notifyAddress" : "ex@example.com",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/1/subscription-settings"
    }
  }
}

Unsubscription Settings

A Unsubscription Setting holds the configuration for the unsubscription. Each Unsubscription Setting belongs to a list

Retrieve single unsubscription setting

GET /lists/{listId}/unsubscription-settings

Request Structure

Table 12. /customer/rest/v1/lists/{listId}/unsubscription-settings
Parameter Description

listId

The ID of the list to get the unsubscription-settings from.

Response structure

Path Type Description

unsubscriptionType

Number

The subscription type, 1 if confirmed opt-out, 2 if double opt-out

verificationMailingId

Number

The id of the mail, which should be send to confirm the unsubscription

sendDooVerificationTimeoutMessage

Boolean

If a mail should be send if double opt-out is expired

verificationTimeoutMailingId

Number

The id of the mail, which should be send if the double opt-out is expired

goodByeMailingId

Number

The id of the goodbye message

dooConfirmationDuration

Number

The duration in days, in which the double opt-out must be confirmed

dooLandingPage

String

The landing page if the double opt-out is already confirmed

dooTimeoutLandingPage

String

The landing page if the double opt-out is expired

deleteMember

Boolean

If unused members should be deleted

preUnsubscriptionType

Number

The preUnsubscriptionType: 0 = without, 1 = direct, 2 = jsp, 3 = external

unsubscriptionLandingPage

String

The landing page for the unsubscription

externalUnsubscriptionLandingPage

String

The external landing page for the unsubscription

unsubscribeJSP

Number

The id of the jsp

verificationNotifyMailSendUnsubscription

Boolean

If notification should be for unconfirmed unsubscriptions

sendNotifyMail

Boolean

If notification mails should be send when a unsubscription happens

sendGoodByeMessage

Boolean

If a goodbye message should be send to the unsubscriber

unsubscriptionCommand

String

The command for the unsubscription

notifyAddress

String

The email address to send notifications to

_links

Object

Links to other resources

Example

Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1114

{
  "verificationMailingId" : 3,
  "verificationTimeoutMailingId" : 3,
  "notifyAddress" : "notify-me@example.com",
  "dooLandingPage" : "https://example.com/error",
  "unsubscriptionType" : 1,
  "sendDooVerificationTimeoutMessage" : false,
  "sendGoodByeMessage" : false,
  "goodByeMailingId" : 12,
  "dooConfirmationDuration" : 30,
  "dooTimeoutLandingPage" : "https://example.com/expired",
  "deleteMember" : false,
  "unsubscriptionCommand" : "unsubscribe",
  "preUnsubscriptionType" : 1,
  "unsubscriptionLandingPage" : "https://example.com/unsubscribe",
  "externalUnsubscriptionLandingPage" : "https://example.com/unsubscribe",
  "unsubscribeJSP" : 2,
  "verificationNotifyMailSendUnsubscription" : false,
  "sendNotifyMail" : false,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/1/unsubscription-settings"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/1"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Edit unsubscription setting

A PUT request with the following payload structure will replace the subscription-settings for an existing list.

  • PUT request on list, which are not of type standard will return a 400 response.

  • PUT request with none existing mailing id ("verificationMailingId" or "verificationTimeoutMailingId" or "goodByeMailingId") will return a 400 response.

  • PUT request with mailing id ("verificationMailingId" or "verificationTimeoutMailingId" or "goodByeMailingId") that belongs to different list return a 400 response.

  • PUT request on non-existing lists will return 404.

Payload structure

PUT /customer/rest/v1/lists/1/unsubscription-settings HTTP/1.1
Content-Type: application/hal+json
Content-Length: 753
Host: api.inxmail.com

{
  "externalUnsubscriptionLandingPage" : "https://example.com/unsubscribe",
  "dooConfirmationDuration" : 30,
  "verificationMailingId" : 3,
  "sendNotifyMail" : false,
  "deleteMember" : false,
  "sendDooVerificationTimeoutMessage" : false,
  "unsubscribeJSP" : 2,
  "preUnsubscriptionType" : 1,
  "dooTimeoutLandingPage" : "https://example.com/expired",
  "sendGoodByeMessage" : false,
  "id" : 0,
  "unsubscriptionLandingPage" : "https://example.com/unsubscribe",
  "unsubscriptionType" : 1,
  "verificationTimeoutMailingId" : 3,
  "unsubscriptionCommand" : "unsubscribe",
  "dooLandingPage" : "https://example.com/error",
  "goodByeMailingId" : 12,
  "notifyAddress" : "notify-me@example.com",
  "verificationNotifyMailSendUnsubscription" : false
}

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/lists/1/unsubscription-settings' -i -X PUT \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "externalUnsubscriptionLandingPage" : "https://example.com/unsubscribe",
  "dooConfirmationDuration" : 30,
  "verificationMailingId" : 3,
  "sendNotifyMail" : false,
  "deleteMember" : false,
  "sendDooVerificationTimeoutMessage" : false,
  "unsubscribeJSP" : 2,
  "preUnsubscriptionType" : 1,
  "dooTimeoutLandingPage" : "https://example.com/expired",
  "sendGoodByeMessage" : false,
  "id" : 0,
  "unsubscriptionLandingPage" : "https://example.com/unsubscribe",
  "unsubscriptionType" : 1,
  "verificationTimeoutMailingId" : 3,
  "unsubscriptionCommand" : "unsubscribe",
  "dooLandingPage" : "https://example.com/error",
  "goodByeMailingId" : 12,
  "notifyAddress" : "notify-me@example.com",
  "verificationNotifyMailSendUnsubscription" : false
}'
Response
{
  "verificationMailingId" : 3,
  "verificationTimeoutMailingId" : 3,
  "notifyAddress" : "notify-me@example.com",
  "dooLandingPage" : "https://example.com/error",
  "unsubscriptionType" : 1,
  "sendDooVerificationTimeoutMessage" : false,
  "sendGoodByeMessage" : false,
  "goodByeMailingId" : 12,
  "dooConfirmationDuration" : 30,
  "dooTimeoutLandingPage" : "https://example.com/expired",
  "deleteMember" : false,
  "unsubscriptionCommand" : "unsubscribe",
  "preUnsubscriptionType" : 1,
  "unsubscriptionLandingPage" : "https://example.com/unsubscribe",
  "externalUnsubscriptionLandingPage" : "https://example.com/unsubscribe",
  "unsubscribeJSP" : 2,
  "verificationNotifyMailSendUnsubscription" : false,
  "sendNotifyMail" : false,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/1/unsubscription-settings"
    }
  }
}

Mailings

An Inxmail Professional mailing describes an email object that is used to send out personalized email content to the recipients of the mailing list it belongs to. Depending on its type it is used for different types of dispatch use-cases like a mass dispatch (e.g. newsletter) or a transactional dispatch (e.g. birthday mailing). See mailing type for a description of all available types.

The mailing object contains various links that can be used as an entry point to gather additional information which are related to a mailing e.g. the rendered content or response information.

If you need more specific information about a mailing, there are separate endpoints for the specific mailing types available. These are described later.

Mailing type

Every mailing has one of the following types:

Mailing Type Description

REGULAR_MAILING

Used for regular newsletter mailings

ACTION_MAILING

Used for action trigger mailings, to respond to an action that occurred in Inxmail Professional

TIME_TRIGGER_MAILING

Used for time trigger mailings, e.g. birthday and interval mailing

SUBSCRIPTION_TRIGGER_MAILING

Used for subscription and unsubscription trigger mailings, e.g. welcome and verification mailing

SPLIT_TEST_MAILING

Used for split test mailings

Retrieve single mailing

GET /mailings/{id}{?embedded}

A GET request with an ID parameter will return the requested mailing.

Request structure

Table 13. /customer/rest/v1/mailings/{id}
Parameter Description

id

The ID of the mailing

Request parameters

Parameter Required Description

embedded

no

Indicates the relations of the resources that should be embedded in the result.

Embeddable relations

Relation Description

inx:sending-statistics

Statistics regarding the sending of this mailing. Only available for mailings of type REGULAR_MAILING.

inx:response-statistics

Statistics regarding the recipient responses (e.g. clicks) to this mailing. Only available for mailings of type REGULAR_MAILING.

Response structure

Path Type Description

id

Number

The ID of the mailing

type

String

The type of the mailing. Possible values are [REGULAR_MAILING, ACTION_MAILING, TIME_TRIGGER_MAILING, SUBSCRIPTION_TRIGGER_MAILING, SPLIT_TEST_MAILING]

listId

Number

The ID of the associated list

name

String

The name of the mailing

subject

String

The subject of the mailing

creationDate

String

The creation date of this mailing

modificationDate

String

The modification date of this mailing

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings/1?embedded=inx:response-statistics,inx:sending-statistics' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1139

{
  "name" : "Name of the mailing",
  "id" : 1,
  "type" : "REGULAR_MAILING",
  "listId" : 42,
  "creationDate" : "2024-11-19T08:47:42Z",
  "subject" : "Subject of the mailing",
  "modificationDate" : "2024-11-19T08:47:42Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1"
    },
    "inx:renderedContent" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/renderedContent"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
    },
    "inx:sendings" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=1"
    },
    "inx:clicks" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=1"
    },
    "inx:web-beacon-hits" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=1"
    },
    "inx:links" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/links"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve mailing collection

GET /mailings{?createdAfter,createdBefore,modifiedAfter,modifiedBefore,sentAfter,types,listIds,readyToSend,isApproved,hasSending,embedded}

A GET request on the mailings resource will return the first page of mailings.

Request parameters

Parameter Required Description

sentAfter

no

All mailings that were sent after this date (ISO 8601) will be returned. When this value is set, only mailings that have at least one successful sending after that given date (inclusive) will be included in the result. Only one value at a time can be specified.

types

no

The mailing type for the desired mailings. More than one value can be specified with multiple query parameters or comma separated list. Default is all mailing types. Possible values are: [REGULAR_MAILING, ACTION_MAILING, TIME_TRIGGER_MAILING, SUBSCRIPTION_TRIGGER_MAILING, SPLIT_TEST_MAILING].

listIds

no

The IDs of the lists to retrieve mailings for. More than one value can be specified with multiple query parameters or comma separated list. Default is all listIds.

readyToSend

no

If true, only mailings of type REGULAR_MAILING will be returned, which are ready to be sent. Mailings which have already been sent or have been interrupted will not be included. Value false has not been implemented yet. Using false will result in 400 Bad Request.

isApproved

no

If false, only mailings which are in mailing state "draft" or "approval requested" will be returned. Value true will return the mailings which are in other mailing states. If there are no mailings matching the filter, an empty list will be returned.

hasSending

no

If false, only mailings that have not been sent will be returned. Value true will return the mailings that have already been sent. If there are no mailings matching the filter, an empty list will be returned. The filter can not be combined with the sentAfter filter.

embedded

no

Indicates the relations of the resources that should be embedded in the result.

createdAfter

no

All mailings that were created after this date (ISO 8601) will be returned. Only one value at a time can be specified.

createdBefore

no

All mailings that were created before this date (ISO 8601) will be returned. Only one value at a time can be specified.

modifiedAfter

no

All mailings that were modified after this date (ISO 8601) will be returned. Only one value at a time can be specified.

modifiedBefore

no

All mailings that were modified before this date (ISO 8601) will be returned. Only one value at a time can be specified.

Embeddable relations

Relation Description

inx:sending-statistics

Statistics regarding the sending of this mailing. Only available for mailings of type REGULAR_MAILING.

inx:response-statistics

Statistics regarding the recipient responses (e.g. clicks) to this mailing. Only available for mailings of type REGULAR_MAILING.

Response structure

See section pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 6033

{
  "_embedded" : {
    "inx:mailings" : [ {
      "name" : "Name of the mailing",
      "id" : 1,
      "type" : "REGULAR_MAILING",
      "listId" : 42,
      "creationDate" : "2024-11-19T08:47:41Z",
      "subject" : "Subject of the mailing",
      "modificationDate" : "2024-11-19T08:47:41Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1"
        },
        "inx:renderedContent" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/renderedContent"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
        },
        "inx:sendings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=1"
        },
        "inx:clicks" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=1"
        },
        "inx:web-beacon-hits" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=1"
        },
        "inx:links" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/links"
        }
      }
    }, {
      "name" : "Name of the mailing",
      "id" : 2,
      "type" : "ACTION_MAILING",
      "listId" : 42,
      "creationDate" : "2024-11-19T08:47:41Z",
      "subject" : "Subject of the mailing",
      "modificationDate" : "2024-11-19T08:47:41Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/2"
        },
        "inx:renderedContent" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/2/renderedContent"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
        },
        "inx:sendings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=2"
        },
        "inx:clicks" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=2"
        },
        "inx:web-beacon-hits" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=2"
        },
        "inx:links" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/2/links"
        }
      }
    }, {
      "name" : "Name of the mailing",
      "id" : 3,
      "type" : "TIME_TRIGGER_MAILING",
      "listId" : 42,
      "creationDate" : "2024-11-19T08:47:41Z",
      "subject" : "Subject of the mailing",
      "modificationDate" : "2024-11-19T08:47:41Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/3"
        },
        "inx:renderedContent" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/3/renderedContent"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
        },
        "inx:sendings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=3"
        },
        "inx:clicks" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=3"
        },
        "inx:web-beacon-hits" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=3"
        },
        "inx:links" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/3/links"
        }
      }
    }, {
      "name" : "Name of the mailing",
      "id" : 4,
      "type" : "SUBSCRIPTION_TRIGGER_MAILING",
      "listId" : 42,
      "creationDate" : "2024-11-19T08:47:41Z",
      "subject" : "Subject of the mailing",
      "modificationDate" : "2024-11-19T08:47:41Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/4"
        },
        "inx:renderedContent" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/4/renderedContent"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
        },
        "inx:sendings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=4"
        },
        "inx:clicks" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=4"
        },
        "inx:web-beacon-hits" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=4"
        },
        "inx:links" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/4/links"
        }
      }
    }, {
      "name" : "Name of the mailing",
      "id" : 6,
      "type" : "SPLIT_TEST_MAILING",
      "listId" : 42,
      "creationDate" : "2024-11-19T08:47:41Z",
      "subject" : "Subject of the mailing",
      "modificationDate" : "2024-11-19T08:47:41Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/6"
        },
        "inx:renderedContent" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/6/renderedContent"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
        },
        "inx:sendings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=6"
        },
        "inx:clicks" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=6"
        },
        "inx:web-beacon-hits" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=6"
        },
        "inx:links" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/6/links"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings?afterId=0&pageSize=5"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings?afterId=6&pageSize=5"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Regular Mailings

Regular mailings are used for standard newsletter campaigns. They are sent at defined period of time and may be re-sent as a single mail (See Send a single mailing / send/continue a mass mailing), or if the 'Send most recently sent mailing in this list to new recipient' option is selected in subscriptions. Unlike trigger- or actionmailings they are not triggered by an event.

There is a specific endpoint to retrieve regular mailings. Only mailings of type REGULAR_MAILING are returned using this endpoint. Regular mailings have all attributes of general mailings and additionally the mailing state. The regular mailing object contains various links that can be used as an entry point to gather additional information which are related to a mailing e.g. the rendered content or response information.

Retrieve single regular mailing

GET /regular-mailings/{id}{?embedded}

A GET request with an ID parameter will return the requested regular mailing.

Request structure

Table 14. /customer/rest/v1/regular-mailings/{id}
Parameter Description

id

The ID of the mailing

Request parameters

Parameter Required Description

embedded

no

Indicates the relations of the resources that should be embedded in the result.

Embeddable relations

Relation Description

inx:editor-content

The text and html content of this mailing. Only available for mailings of type REGULAR_MAILING.

inx:sending-statistics

Statistics regarding the sending of this mailing. Only available for mailings of type REGULAR_MAILING.

inx:response-statistics

Statistics regarding the recipient responses (e.g. clicks) to this mailing. Only available for mailings of type REGULAR_MAILING.

Response structure

Path Type Description

id

Number

The ID of the mailing

listId

Number

The ID of the associated list

name

String

The name of the mailing

type

String

The type of the mailing. Always "REGULAR_MAILING"

subject

String

The subject of the mailing

mailingState

String

The state of the mailing. The state can be on of the values FINISHED, ACTIVE, DRAFT , INTERRUPTED, SCHEDULED, APPROVAL_REQUESTED or APPROVED

creationDate

String

The creation date of this mailing

modificationDate

String

The modification date of this mailing

editorContentType

String

The editor content type of the mailing. Values are TEXT; HTML; TEXT_HTML, XML_TEXT, XML_HTML and XML_TEXT_HTML

scheduleDate

String

The date a Mailing is due to be sent

targetGroupConfiguration.combination

String

The filter configuration applied to the retrieved Mailing. Combination types are MATCH_NONE, MATCH_ONE, MATCH_ALL, FILTER_GROUP_NOT_ASSIGNED

targetGroupConfiguration.targetGroups

Array

The IDs of the filters applied to the retrieved Mailing.

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/1?embedded=inx:response-statistics,inx:sending-statistics,inx:editor-content' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1510

{
  "name" : "Name of the mailing",
  "id" : 1,
  "type" : "REGULAR_MAILING",
  "listId" : 42,
  "creationDate" : "2024-11-19T08:47:44Z",
  "scheduleDate" : "2024-11-19T08:47:43Z",
  "subject" : "Subject of the mailing",
  "modificationDate" : "2024-11-19T08:47:44Z",
  "mailingState" : "DRAFT",
  "editorContentType" : "TEXT_HTML",
  "targetGroupConfiguration" : {
    "combination" : "FILTER_GROUP_NOT_ASSIGNED",
    "targetGroups" : [ ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/1"
    },
    "inx:renderedContent" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/1/renderedContent"
    },
    "inx:editorContent" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/1/editor-content"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
    },
    "inx:sendings" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=1"
    },
    "inx:clicks" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=1"
    },
    "inx:web-beacon-hits" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=1"
    },
    "inx:links" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/1/links"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Create regular mailing

POST /regular-mailings

A POST request with the following payload structure will create a new regular mailing. Violations of the constraints will lead to validation errors.

Payload structure

Path Type Description Constraints

name

String

The name of the new mailing

  • Must not be null

  • Size must be between 1 and 255 inclusive

subject

String

The subject of the new mailing

  • Must not be null

  • Size must be between 1 and 1024 inclusive

listId

Number

The listId of the new mailing. List must be of type STANDARD or DYNAMIC.

  • Must not be null

editorContentType

String

The editor content type of the new mailing. Possible values are "TEXT", "HTML" AND "TEXT_HTML"

  • Must not be null

text

String

The text part of the editor content of the mailing

html

String

The html part of the editor content of the mailing

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "name" : "name",
  "subject" : "subject",
  "listId" : 5,
  "editorContentType" : "TEXT_HTML",
  "text" : "text",
  "html" : "html"
}'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/regular-mailings/5
Content-Type: application/hal+json
Content-Length: 229

{
  "id" : 5,
  "name" : "name",
  "subject" : "subject",
  "listId" : 5,
  "editorContentType" : "TEXT_HTML",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/5"
    }
  }
}

Copy regular mailing with XML content

It is possible to copy a regular mailing, which has editorContentType XML_TEXT_HTML, XML_HTML or XML_TEXT. Based on the design collection a new mailing is created and filled it with the specified content.

Payload structure

Path Type Description Constraints

name

String

The name of the new mailing

  • Must not be null

  • Size must be between 1 and 255 inclusive

subject

String

The subject of the new mailing

  • Must not be null

  • Size must be between 1 and 1024 inclusive

listId

Number

The listId of the new mailing. List must be of type STANDARD or DYNAMIC.

  • Must not be null

editorContentType

String

The editor content type of the new mailing. Possible values are "XML_TEXT_HTML", "XML_HTML" AND "XML_TEXT"

  • Must not be null

designCollectionId

Number

The designCollectionId to use for a mailing with editorContenType XML.

xmlContentBase64

String

The xml content as Base64 coded string

styleName

String

Optional parameter for the xsl style name of the template. If not entered, the first xsl style is used, which does not start or end with the sting "TEXT"

templateName

String

Optional parameter for the template name of the design collection. Must be specified, if more than one template is in the design collection.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "name" : "name",
  "subject" : "subject",
  "listId" : 5,
  "editorContentType" : "XML_TEXT_HTML",
  "designCollectionId" : 405,
  "xmlContentBase64" : "BD544543534...",
  "styleName" : "Standard",
  "templateName" : "Newsletter"
}'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/regular-mailings/5
Content-Type: application/hal+json
Content-Length: 324

{
  "id" : 5,
  "name" : "name",
  "subject" : "subject",
  "listId" : 5,
  "editorContentType" : "XML_TEXT_HTML",
  "designCollectionId" : 405,
  "styleName" : "Standard",
  "templateName" : "Newsletter",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/5"
    }
  }
}

Update a regular mailing

PATCH /regular-mailings/{id}

A PATCH request with the following payload structure will modify a regular mailing. Violations of the constraints will lead to validation errors.

The fields text and html are dependent of the editor content type. For example for a text-only mailing, the field html can not be used in an update call.

The state of the mailing must be DRAFT, otherwise the mailing can not be updated.

Payload structure

Path Type Description Constraints

name

String

The new name of the mailing

subject

String

The new subject of the mailing

text

String

The new text editor content of the mailing

html

String

The new html editor content of the mailing

targetGroupConfiguration

Object

The target group configuration of the mailing

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/5' -i -X PATCH \
    -H 'Content-Type: application/merge-patch+json' \
    -d '{
  "targetGroupConfiguration" : {
    "combination" : "MATCH_ALL",
    "targetGroups" : [ {
      "targetGroupId" : 1
    } ]
  },
  "name" : "patched name",
  "subject" : "patched subject",
  "text" : "patched text",
  "html" : "patched html"
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 535

{
  "name" : "patched name",
  "id" : 5,
  "type" : "REGULAR_MAILING",
  "listId" : 1,
  "creationDate" : null,
  "scheduleDate" : null,
  "subject" : "patched subject",
  "modificationDate" : null,
  "mailingState" : "DRAFT",
  "editorContentType" : null,
  "targetGroupConfiguration" : {
    "combination" : "MATCH_ALL",
    "targetGroups" : [ {
      "targetGroupId" : 1
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/5?embedded=inx%3Aeditor-content"
    }
  }
}

Delete a regular mailing

DELETE /regular-mailings/{id}

A DELETE request on a single regular mailing will delete that mailing.

If a mailing is currently locked, it cannot be deleted.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/5' -i -X DELETE
Response
HTTP/1.1 204 No Content

Retrieve editor content of a regular mailing

GET /regular-mailings/{id}/editor-content

A GET request with an ID parameter will return the editor content of the requested regular mailing.

Request structure

Table 15. /customer/rest/v1/regular-mailings/{id}/editor-content
Parameter Description

id

The ID of the mailing

Response structure

{
  "text" : "text",
  "html" : "html",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/1/editor-content"
    }
  }
}

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/1/editor-content' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 173

{
  "text" : "text",
  "html" : "html",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/1/editor-content"
    }
  }
}

Schedule a regular mailing

POST /regular-mailings/{id}/schedule

A POST request on the schedule subresource of the regular mailings resource will set the schedule date (ISO 8601). Only mailings that are in APPROVED state when performing this operation can be scheduled.

Path Type Description Constraints

scheduleDate

String

The schedule date (ISO 8601) of the mailing

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/5/schedule' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "scheduleDate" : "2025-11-19T08:47:45+0000"
}'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/regular-mailings/5/schedule
Content-Type: application/hal+json
Content-Length: 184

{
  "id" : 5,
  "scheduleDate" : "2025-11-19T08:47:45Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/5/schedule"
    }
  }
}

Reschedule a regular mailing

PUT /regular-mailings/{id}/schedule

A PUT request on the schedule subresource of the regular mailings resource will set the schedule date (ISO 8601). Only mailings that are in SCHEDULED state when performing this operation can be rescheduled.

Path Type Description Constraints

scheduleDate

String

The schedule date (ISO 8601) of the mailing

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/5/schedule' -i -X PUT \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "scheduleDate" : "2025-11-19T08:47:45+0000"
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 184

{
  "id" : 5,
  "scheduleDate" : "2025-11-19T08:47:45Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/5/schedule"
    }
  }
}

Unschedule a regular mailing

DELETE /regular-mailings/{id}/schedule

A DELETE request on the schedule subresource of the regular mailings resource will unset the schedule date (ISO 8601). Only mailings in the state SCHEDULED can be unscheduled. Once the date of sending is reached and the sending starts the mailing will transition its state into ACTIVE. At that point the mailing can no longer be unscheduled.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/5/schedule' -i -X DELETE
Response
HTTP/1.1 204 No Content

Retrieve schedule of a regular mailing

GET /regular-mailings/{id}/schedule

A GET request on the schedule subresource of the regular mailings resource will get the schedule date.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/1/schedule' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 184

{
  "id" : 1,
  "scheduleDate" : "2025-11-19T08:47:44Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/1/schedule"
    }
  }
}

Retrieve regular mailing collection

GET /regular-mailings{?createdAfter,createdBefore,modifiedAfter,modifiedBefore,sentAfter,sentBefore,types,listIds,readyToSend,mailingStates,embedded}

A GET request on the regular mailings resource will return the first page of mailings.

Request parameters

Parameter Required Description

sentAfter

no

All mailings that were sent after this date (ISO 8601) will be returned. When this value is set, only mailings that have at least one successful sending after that given date (inclusive) will be included in the result. Only one value at a time can be specified. Matches the end of the send duration, see hint below.

sentBefore

no

All mailings that were sent before this date (ISO 8601) will be returned. When this value is set, only mailings that have at least one successful sending before that given date (exclusive) will be included in the result. Only one value at a time can be specified. Matches the end of the send duration, see hint below.

types

no

The mailing type for the desired mailings. More than one value can be specified with multiple query parameters or comma separated list. Default is all mailing types. Possible values are: [REGULAR_MAILING, ACTION_MAILING, TIME_TRIGGER_MAILING, SUBSCRIPTION_TRIGGER_MAILING, SPLIT_TEST_MAILING].

listIds

no

The IDs of the lists to retrieve mailings for. More than one value can be specified with multiple query parameters or comma separated list. Default is all listIds.

readyToSend

no

If true, only mailings of type REGULAR_MAILING will be returned, which are ready to be sent. Mailings which have already been sent or have been interrupted will not be included. Value false has not been implemented yet. Using false will result in 400 Bad Request.

embedded

no

Indicates the relations of the resources that should be embedded in the result.

createdAfter

no

All mailings that were created after this date (ISO 8601) will be returned. Only one value at a time can be specified.

createdBefore

no

All mailings that were created before this date (ISO 8601) will be returned. Only one value at a time can be specified.

modifiedAfter

no

All mailings that were modified after this date (ISO 8601) will be returned. Only one value at a time can be specified.

modifiedBefore

no

All mailings that were modified before this date (ISO 8601) will be returned. Only one value at a time can be specified.

mailingStates

no

All mailings of specified RegularMailingState will be returned. More than one value can be specified with multiple query parameters or comma separated list. Valid states are FINISHED, ACTIVE, DRAFT, INTERRUPTED, SCHEDULED, APPROVAL_REQUESTED or APPROVED

Hint: The sentBefore and sentAfter filter match the end of a sendings send-duration. A sending of a mailing is not an instantenious event. If a mailing is sent to millions of recipients, possibly with additional target groups, the duration of sending these mails could span more than an hour. With small sendings the duration is most often more than one second. Effectively, sentBefore means the send-duration ended before that point in time. sentAfter means the send-duration ended after that point in time.

Embeddable relations

Relation Description

inx:response-statistics

Statistics regarding the recipient responses (e.g. clicks) to this mailing. Only available for mailings of type REGULAR_MAILING.

inx:sending-statistics

Statistics regarding the sending of this mailing. Only available for mailings of type REGULAR_MAILING.

Response structure

See section pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings?createdAfter=2017-10-10T00:00:00Z&createdBefore=2019-10-10T00:00:00Z&modifiedAfter=2017-11-11T00:00:00Z&modifiedBefore=2019-11-11T00:00:00Z&sentAfter=2018-03-27T08:00:00Z&sentBefore=2021-03-27T08:00:00Z&types=REGULAR_MAILING&listIds=1337&readyToSend=true&mailingStates=FINISHED&mailingStates=DRAFT&embedded=inx:response-statistics,inx:sending-statistics' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 11673

{
  "_embedded" : {
    "inx:regular-mailings" : [ {
      "name" : "Name of the mailing",
      "id" : 1,
      "type" : "REGULAR_MAILING",
      "listId" : 42,
      "creationDate" : "2024-11-19T08:47:44Z",
      "scheduleDate" : "2024-11-19T08:47:43Z",
      "subject" : "Subject of the mailing",
      "modificationDate" : "2024-11-19T08:47:44Z",
      "mailingState" : "DRAFT",
      "editorContentType" : "TEXT_HTML",
      "targetGroupConfiguration" : {
        "combination" : "FILTER_GROUP_NOT_ASSIGNED",
        "targetGroups" : [ ]
      },
      "_embedded" : {
        "inx:response-statistics" : {
          "openingRecipients" : 1000,
          "botInteractions" : 0,
          "openingRate" : 0.1,
          "totalClicks" : 1000,
          "clickingRecipients" : 500,
          "uniqueClickRate" : 0.05,
          "ctor" : 0.5,
          "unsubscribeClicks" : 0,
          "listUnsubscribeClicks" : 0,
          "unsubscribeRate" : 0.0,
          "statisticsByLink" : null,
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/statistics/responses?mailingId=1&includeLinkData=false"
            }
          }
        },
        "inx:sending-statistics" : {
          "startDate" : "2024-11-19T08:47:44Z",
          "endDate" : "2024-11-19T08:47:44Z",
          "mailsPerHour" : 1000000.0,
          "recipientsCount" : 10000,
          "deliveredMailsCount" : 10000,
          "sentErrorCount" : 0,
          "bounceCount" : 0,
          "notSentMailsCount" : 0,
          "averageMailSize" : 102400.0,
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/statistics/sendings?mailingId=1"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/1"
        },
        "inx:renderedContent" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/1/renderedContent"
        },
        "inx:editorContent" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/1/editor-content"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
        },
        "inx:sendings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=1"
        },
        "inx:clicks" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=1"
        },
        "inx:web-beacon-hits" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=1"
        },
        "inx:links" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/1/links"
        }
      }
    }, {
      "name" : "Name of the mailing",
      "id" : 2,
      "type" : "REGULAR_MAILING",
      "listId" : 42,
      "creationDate" : "2024-11-19T08:47:44Z",
      "scheduleDate" : "2024-11-19T08:47:43Z",
      "subject" : "Subject of the mailing",
      "modificationDate" : "2024-11-19T08:47:44Z",
      "mailingState" : "DRAFT",
      "editorContentType" : "TEXT_HTML",
      "targetGroupConfiguration" : {
        "combination" : "FILTER_GROUP_NOT_ASSIGNED",
        "targetGroups" : [ ]
      },
      "_embedded" : {
        "inx:response-statistics" : {
          "openingRecipients" : 1000,
          "botInteractions" : 0,
          "openingRate" : 0.1,
          "totalClicks" : 1000,
          "clickingRecipients" : 500,
          "uniqueClickRate" : 0.05,
          "ctor" : 0.5,
          "unsubscribeClicks" : 0,
          "listUnsubscribeClicks" : 0,
          "unsubscribeRate" : 0.0,
          "statisticsByLink" : null,
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/statistics/responses?mailingId=2&includeLinkData=false"
            }
          }
        },
        "inx:sending-statistics" : {
          "startDate" : "2024-11-19T08:47:44Z",
          "endDate" : "2024-11-19T08:47:44Z",
          "mailsPerHour" : 1000000.0,
          "recipientsCount" : 10000,
          "deliveredMailsCount" : 10000,
          "sentErrorCount" : 0,
          "bounceCount" : 0,
          "notSentMailsCount" : 0,
          "averageMailSize" : 102400.0,
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/statistics/sendings?mailingId=2"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/2"
        },
        "inx:renderedContent" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/2/renderedContent"
        },
        "inx:editorContent" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/2/editor-content"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
        },
        "inx:sendings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=2"
        },
        "inx:clicks" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=2"
        },
        "inx:web-beacon-hits" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=2"
        },
        "inx:links" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/2/links"
        }
      }
    }, {
      "name" : "Name of the mailing",
      "id" : 3,
      "type" : "REGULAR_MAILING",
      "listId" : 42,
      "creationDate" : "2024-11-19T08:47:44Z",
      "scheduleDate" : "2024-11-19T08:47:43Z",
      "subject" : "Subject of the mailing",
      "modificationDate" : "2024-11-19T08:47:44Z",
      "mailingState" : "DRAFT",
      "editorContentType" : "TEXT_HTML",
      "targetGroupConfiguration" : {
        "combination" : "FILTER_GROUP_NOT_ASSIGNED",
        "targetGroups" : [ ]
      },
      "_embedded" : {
        "inx:response-statistics" : {
          "openingRecipients" : 1000,
          "botInteractions" : 0,
          "openingRate" : 0.1,
          "totalClicks" : 1000,
          "clickingRecipients" : 500,
          "uniqueClickRate" : 0.05,
          "ctor" : 0.5,
          "unsubscribeClicks" : 0,
          "listUnsubscribeClicks" : 0,
          "unsubscribeRate" : 0.0,
          "statisticsByLink" : null,
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/statistics/responses?mailingId=3&includeLinkData=false"
            }
          }
        },
        "inx:sending-statistics" : {
          "startDate" : "2024-11-19T08:47:44Z",
          "endDate" : "2024-11-19T08:47:44Z",
          "mailsPerHour" : 1000000.0,
          "recipientsCount" : 10000,
          "deliveredMailsCount" : 10000,
          "sentErrorCount" : 0,
          "bounceCount" : 0,
          "notSentMailsCount" : 0,
          "averageMailSize" : 102400.0,
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/statistics/sendings?mailingId=3"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/3"
        },
        "inx:renderedContent" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/3/renderedContent"
        },
        "inx:editorContent" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/3/editor-content"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
        },
        "inx:sendings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=3"
        },
        "inx:clicks" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=3"
        },
        "inx:web-beacon-hits" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=3"
        },
        "inx:links" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/3/links"
        }
      }
    }, {
      "name" : "Name of the mailing",
      "id" : 4,
      "type" : "REGULAR_MAILING",
      "listId" : 42,
      "creationDate" : "2024-11-19T08:47:44Z",
      "scheduleDate" : "2024-11-19T08:47:43Z",
      "subject" : "Subject of the mailing",
      "modificationDate" : "2024-11-19T08:47:44Z",
      "mailingState" : "DRAFT",
      "editorContentType" : "TEXT_HTML",
      "targetGroupConfiguration" : {
        "combination" : "FILTER_GROUP_NOT_ASSIGNED",
        "targetGroups" : [ ]
      },
      "_embedded" : {
        "inx:response-statistics" : {
          "openingRecipients" : 1000,
          "botInteractions" : 0,
          "openingRate" : 0.1,
          "totalClicks" : 1000,
          "clickingRecipients" : 500,
          "uniqueClickRate" : 0.05,
          "ctor" : 0.5,
          "unsubscribeClicks" : 0,
          "listUnsubscribeClicks" : 0,
          "unsubscribeRate" : 0.0,
          "statisticsByLink" : null,
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/statistics/responses?mailingId=4&includeLinkData=false"
            }
          }
        },
        "inx:sending-statistics" : {
          "startDate" : "2024-11-19T08:47:44Z",
          "endDate" : "2024-11-19T08:47:44Z",
          "mailsPerHour" : 1000000.0,
          "recipientsCount" : 10000,
          "deliveredMailsCount" : 10000,
          "sentErrorCount" : 0,
          "bounceCount" : 0,
          "notSentMailsCount" : 0,
          "averageMailSize" : 102400.0,
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/statistics/sendings?mailingId=4"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/4"
        },
        "inx:renderedContent" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/4/renderedContent"
        },
        "inx:editorContent" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/4/editor-content"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
        },
        "inx:sendings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=4"
        },
        "inx:clicks" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=4"
        },
        "inx:web-beacon-hits" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=4"
        },
        "inx:links" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings/4/links"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/regular-mailings?afterId=0&pageSize=6&embedded=inx%3Aresponse-statistics&embedded=inx%3Asending-statistics&sentAfter=2018-03-27T08%3A00%3A00Z&sentBefore=2020-12-27T08%3A00%3A00Z&listIds=1337&readyToSend=true&createdAfter=2017-10-10T00%3A00%3A00Z&createdBefore=2019-10-10T00%3A00%3A00Z&modifiedAfter=2017-11-11T00%3A00%3A00Z&modifiedBefore=2019-11-11T00%3A00%3A00Z&mailingStates=FINISHED&mailingStates=DRAFT"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Split-Test-Mailings

With split tests you can create different versions of a mailing. After dispatch, you can also analyse important key performance indicators for the individual mailing versions.

There is a specific endpoint to split test mailings. Only mailings of type SPLIT_TEST_MAILING are returned using this endpoint. Split tests mailings have all attributes of general mailings and additionally a specific mailing state. The split test mailing object contains various links that can be used as an entry point to gather additional information which are related to a mailing e.g. the rendered content or response information.

Retrieve single splittest mailing

GET /split-test-mailings/{id}

A GET request with an ID parameter will return the requested regular mailing.

Request structure

Table 16. /customer/rest/v1/split-test-mailings/{id}
Parameter Description

id

The ID of the mailing

Response structure

Path Type Description

id

Number

The ID of the mailing

listId

Number

The ID of the associated list

name

String

The name of the mailing

type

String

The type of the mailing. Always "SPLIT_TEST_MAILING"

subject

String

The subject of the mailing

mailingState

String

The state of the mailing. The state can be on of the values FINISHED, ACTIVE, DRAFT, INTERRUPTED, SCHEDULED, APPROVAL_REQUESTED, APPROVED or ASSIGNED

creationDate

String

The creation date of this mailing

modificationDate

String

The modification date of this mailing

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/split-test-mailings/1' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1203

{
  "name" : "Name of the mailing",
  "id" : 1,
  "type" : "SPLIT_TEST_MAILING",
  "listId" : 42,
  "creationDate" : "2024-11-19T08:47:46Z",
  "subject" : "Subject of the mailing",
  "modificationDate" : "2024-11-19T08:47:46Z",
  "mailingState" : "DRAFT",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/split-test-mailings/1"
    },
    "inx:renderedContent" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/split-test-mailings/1/renderedContent"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
    },
    "inx:sendings" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=1"
    },
    "inx:clicks" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=1"
    },
    "inx:web-beacon-hits" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=1"
    },
    "inx:links" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/split-test-mailings/1/links"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve splittest mailing collection

GET /split-test-mailings{?createdAfter,createdBefore,modifiedAfter,modifiedBefore,sentAfter,listIds}

A GET request on the split test mailings resource will return the first page of mailings.

Request parameters

Parameter Required Description

sentAfter

no

All mailings that were sent after this date (ISO 8601) will be returned. When this value is set, only mailings that have at least one successful sending after that given date (inclusive) will be included in the result. Only one value at a time can be specified.

listIds

no

The IDs of the lists to retrieve mailings for. More than one value can be specified with multiple query parameters or comma separated list. Default is all listIds.

createdAfter

no

All mailings that were created after this date (ISO 8601) will be returned. Only one value at a time can be specified.

createdBefore

no

All mailings that were created before this date (ISO 8601) will be returned. Only one value at a time can be specified.

modifiedAfter

no

All mailings that were modified after this date (ISO 8601) will be returned. Only one value at a time can be specified.

modifiedBefore

no

All mailings that were modified before this date (ISO 8601) will be returned. Only one value at a time can be specified.

Response structure

See section pagination.

Action-Mailings

As with timed trigger mailings, action mailings are sent by the system automatically. The event leading to the dispatch of the action mailing is not time-determined. Instead, the sending of action mailings is triggered by the recipient or their email account. There is a specific endpoint for action mailings. Only action mailings of type ACTION_MAILING are returned using this endpoint.

Action mailings include all attributes of general mailings but have a specific mailing state. The action mailing mailing object contains various links that can be used as an entry point to gather additional information which are related to a mailing e.g. the rendered content or response information.

Retrieve single action mailing

GET /action-mailings/{id}

A GET request with an ID parameter will return the requested regular mailing.

Request structure

Table 17. /customer/rest/v1/action-mailings/{id}
Parameter Description

id

The ID of the mailing

Response structure

Path Type Description

id

Number

The ID of the mailing

listId

Number

The ID of the associated list

name

String

The name of the mailing

type

String

The type of the mailing contains always "ACTION_MAILING"

subject

String

The subject of the mailing

mailingState

String

The state of the mailing. The state can be on of the values DRAFT, APPROVAL_REQUESTED, APPROVED, INACTIVE or ACTIVE

creationDate

String

The creation date of this mailing

modificationDate

String

The modification date of this mailing

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/action-mailings/1' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1187

{
  "name" : "Name of the mailing",
  "id" : 1,
  "type" : "ACTION_MAILING",
  "listId" : 42,
  "creationDate" : "2024-11-19T08:47:38Z",
  "subject" : "Subject of the mailing",
  "modificationDate" : "2024-11-19T08:47:38Z",
  "mailingState" : "DRAFT",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/action-mailings/1"
    },
    "inx:renderedContent" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/action-mailings/1/renderedContent"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
    },
    "inx:sendings" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=1"
    },
    "inx:clicks" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=1"
    },
    "inx:web-beacon-hits" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=1"
    },
    "inx:links" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/action-mailings/1/links"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve action mailing collection

GET /action-mailings{?createdAfter,createdBefore,modifiedAfter,modifiedBefore,sentAfter,listIds}

A GET request on the action mailings resource will return the first page of mailings.

Request parameters

Parameter Required Description

sentAfter

no

All mailings that were sent after this date (ISO 8601) will be returned. When this value is set, only mailings that have at least one successful sending after that given date (inclusive) will be included in the result. Only one value at a time can be specified.

listIds

no

The IDs of the lists to retrieve mailings for. More than one value can be specified with multiple query parameters or comma separated list. Default is all listIds.

createdAfter

no

All mailings that were created after this date (ISO 8601) will be returned. Only one value at a time can be specified.

createdBefore

no

All mailings that were created before this date (ISO 8601) will be returned. Only one value at a time can be specified.

modifiedAfter

no

All mailings that were modified after this date (ISO 8601) will be returned. Only one value at a time can be specified.

modifiedBefore

no

All mailings that were modified before this date (ISO 8601) will be returned. Only one value at a time can be specified.

Response structure

See section pagination.

Delete single action mailing

Unresolved directive in mailing/structure.adoc - include::/home/jenkins/agent/workspace/est.documentation_release_4.8.68/xpro-rest-impl/build/generated-snippets/delete-single-action-mailing/uri-template.adoc[]

A DELETE request will remove action mailing and return statusCode=204. In case action mailing by specified id will not be found the response will have statusCode=404.

Example

Request

Unresolved directive in mailing/structure.adoc - include::/home/jenkins/agent/workspace/est.documentation_release_4.8.68/xpro-rest-impl/build/generated-snippets/delete-single-action-mailing/curl-request.adoc[]

Create action mailing

POST /action-mailings

A POST request will create action mailing with mailingState=DRAFT, type=ACTION_MAILING and return statusCode=201. In case payload data is invalid then response will have statusCode=400.

Payload structure

Path Type Description

name

String

Name of the action mailing. Valid length is [1;255]

subject

String

Subject of the action mailing. Valid length is [1;1024]

listId

Number

The ID of the list associated to the action mailing. Only STANDARD lists are available for Action Mailing

editorContentType

String

Type of the content. Next values are valid: [TEXT; HTML; TEXT_HTML].

text

String

Plain text content. Encoding for double quotes is required. Should not be null in case editorContentType=TEXT or TEXT_HTML.

html

String

Html content. Encoding for double quotes is required. Should not be null in case editorContentType=HTML or TEXT_HTML.

Request structure

{
  "id" : 0,
  "name" : "nameValue",
  "subject" : "subjectValue",
  "listId" : 3,
  "editorContentType" : "TEXT_HTML",
  "text" : "plane \"example\" text",
  "html" : "<html><body><h1 align=\"center\">Hallo Ließchen Müller,</h1><br>hier ist Dein Newsletter mit den guten Angeboten.</body></html>"
}

Response structure

Path Type Description

modificationDate

String

Modification date of the action mailing.

mailingState

String

The mailing state of the action trigger

listId

Number

The ID of the list associated to the action mailing. Only STANDARD lists are available for Action Mailing

subject

String

Subject of the action mailing.

creationDate

String

Creation date of the action mailing.

name

String

Name of the action mailing.

id

Number

Id of the created action mailing.

type

String

Type of the created action mailing.

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/action-mailings' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "id" : 0,
  "name" : "nameValue",
  "subject" : "subjectValue",
  "listId" : 3,
  "editorContentType" : "TEXT_HTML",
  "text" : "plane \"example\" text",
  "html" : "<html><body><h1 align=\"center\">Hallo Ließchen Müller,</h1><br>hier ist Dein Newsletter mit den guten Angeboten.</body></html>"
}'

Trigger-Mailings

Trigger mailings are a type of mailings which are sent automatically and repeatedly in time intervals. The recipients of each sending are determined by the settings of the trigger mailing. Examples for time trigger mailings are birthday mailings or interval mailings.

While the mailings endpoint does return trigger mailings with those fields that are common to all mailings, the trigger mailing endpoint returns trigger mailings including fields specific to this type of mailing.

The trigger mailing object contains various links that can be used as an entry point to gather additional information which are related to a mailing e.g. the rendered content or response information.

Retrieve single trigger mailing

GET /trigger-mailings/{id}

A GET request with an ID parameter will return the requested trigger mailing.

Request structure

Table 18. /customer/rest/v1/trigger-mailings/{id}
Parameter Description

id

The ID of the mailing

Response structure

Path Type Description

id

Number

The ID of the mailing

listId

Number

The ID of the associated list

name

String

The name of the mailing

type

String

The type of the mailing. Always "TIME_TRIGGER_MAILING"

subject

String

The subject of the mailing

mailingState

String

The state of the mailing. The state can be on of the values DRAFT, APPROVAL_REQUESTED, APPROVED, INACTIVE or ACTIVE

creationDate

String

The creation date of this mailing

modificationDate

String

The modification date of this mailing

_links

Object

Links to other resources
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1196

{
  "name" : "Name of the mailing",
  "id" : 1,
  "type" : "TIME_TRIGGER_MAILING",
  "listId" : 42,
  "creationDate" : "2024-11-19T08:47:49Z",
  "subject" : "Subject of the mailing",
  "modificationDate" : "2024-11-19T08:47:49Z",
  "mailingState" : "DRAFT",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/trigger-mailings/1"
    },
    "inx:renderedContent" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/trigger-mailings/1/renderedContent"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
    },
    "inx:sendings" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=1"
    },
    "inx:clicks" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=1"
    },
    "inx:web-beacon-hits" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=1"
    },
    "inx:links" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/trigger-mailings/1/links"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Response structure

See section pagination.

Retrieve trigger mailing collection

GET /trigger-mailings{?createdAfter,createdBefore,modifiedAfter,modifiedBefore,sentAfter,listIds}

A GET request on the trigger mailings resource will return the first page of mailings.

Request parameters

Parameter Required Description

sentAfter

no

All mailings that were sent after this date (ISO 8601) will be returned. When this value is set, only mailings that have at least one successful sending after that given date (inclusive) will be included in the result. Only one value at a time can be specified.

listIds

no

The IDs of the lists to retrieve mailings for. More than one value can be specified with multiple query parameters or comma separated list. Default is all listIds.

createdAfter

no

All mailings that were created after this date (ISO 8601) will be returned. Only one value at a time can be specified.

createdBefore

no

All mailings that were created before this date (ISO 8601) will be returned. Only one value at a time can be specified.

modifiedAfter

no

All mailings that were modified after this date (ISO 8601) will be returned. Only one value at a time can be specified.

modifiedBefore

no

All mailings that were modified before this date (ISO 8601) will be returned. Only one value at a time can be specified.

Response structure

See section pagination.

Subscription Mailings

Subscription mailings are triggered by subscription or unsubscription events. They are used by the subscriptions agent to handle notifications in the single/double-opt-in process for subscription or to process an unsubscription.

While the mailings endpoint does return subscription and unsubscription mailings with those fields that are common to all mailings, the subscription mailing endpoint returns subscription mailings including fields specific to this type of mailing.

Subscription mailings have all attributes of general mailings and additionally the mailing state. The subscription test mailing object contains various links that can be used as an entry point to gather additional information which are related to a mailing e.g. the rendered content or response information.

Retrieve single subscription mailing

GET /subscription-mailings/{id}

A GET request with an ID parameter will return the requested subscription mailing.

Request structure

Table 19. /customer/rest/v1/subscription-mailings/{id}
Parameter Description

id

The ID of the mailing

Response structure

Path Type Description

id

Number

The ID of the mailing

listId

Number

The ID of the associated list

name

String

The name of the mailing

type

String

The type of the mailing. Always "SUBSCRIPTION_TRIGGER_MAILING"

subject

String

The subject of the mailing

mailingState

String

The state of the mailing. The state can be on of the values USED, DRAFT, APPROVAL_REQUESTED or APPROVED

creationDate

String

The creation date of this mailing

modificationDate

String

The modification date of this mailing

subscriptionMailingType

String

The subscrption mailing type of the mailing

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/subscription-mailings/1' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1273

{
  "name" : "Name of the mailing",
  "id" : 1,
  "type" : "SUBSCRIPTION_TRIGGER_MAILING",
  "listId" : 42,
  "creationDate" : "2024-11-19T08:47:48Z",
  "subject" : "Subject of the mailing",
  "modificationDate" : "2024-11-19T08:47:48Z",
  "mailingState" : "DRAFT",
  "subscriptionMailingType" : "SUBSCRIPTION_WELCOME",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/subscription-mailings/1"
    },
    "inx:renderedContent" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/subscription-mailings/1/renderedContent"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
    },
    "inx:sendings" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=1"
    },
    "inx:clicks" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=1"
    },
    "inx:web-beacon-hits" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=1"
    },
    "inx:links" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/subscription-mailings/1/links"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve subscription mailing collection

GET /subscription-mailings{?createdAfter,createdBefore,modifiedAfter,modifiedBefore,sentAfter,listIds,readyToSend}

A GET request on the subscription mailings resource will return the first page of mailings.

Request parameters

Parameter Required Description

sentAfter

no

All mailings that were sent after this date (ISO 8601) will be returned. When this value is set, only mailings that have at least one successful sending after that given date (inclusive) will be included in the result. Only one value at a time can be specified.

listIds

no

The IDs of the lists to retrieve mailings for. More than one value can be specified with multiple query parameters or comma separated list. Default is all listIds.

readyToSend

no

If true, only mailings of type SUBSCRIPTION_TRIGGER_MAILING will be returned, which are ready to be sent. Mailings which have already been sent or have been interrupted will not be included. Value false has not been implemented yet. Using false will result in 400 Bad Request.

createdAfter

no

All mailings that were created after this date (ISO 8601) will be returned. Only one value at a time can be specified.

createdBefore

no

All mailings that were created before this date (ISO 8601) will be returned. Only one value at a time can be specified.

modifiedAfter

no

All mailings that were modified after this date (ISO 8601) will be returned. Only one value at a time can be specified.

modifiedBefore

no

All mailings that were modified before this date (ISO 8601) will be returned. Only one value at a time can be specified.

Response structure

See section pagination.

Create subscription mailing

POST /subscription-mailings

A POST request with the following structure will create the requested subscription mailing.

Request structure

{
  "name" : "name",
  "subject" : "subject",
  "listId" : 5,
  "editorContentType" : "TEXT_HTML",
  "text" : "text",
  "html" : "html",
  "subscriptionMailingType" : "SUBSCRIPTION_VERIFICATION"
}

Response structure

{
  "id" : 5,
  "name" : "name",
  "subject" : "subject",
  "listId" : 5,
  "editorContentType" : "TEXT_HTML",
  "text" : "text",
  "html" : "html",
  "subscriptionMailingType" : "SUBSCRIPTION_VERIFICATION",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/subscription-mailings/5"
    }
  }
}

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/subscription-mailings/' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "name" : "name",
  "subject" : "subject",
  "listId" : 5,
  "editorContentType" : "TEXT_HTML",
  "text" : "text",
  "html" : "html",
  "subscriptionMailingType" : "SUBSCRIPTION_VERIFICATION"
}'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/subscription-mailings/5
Content-Type: application/hal+json
Content-Length: 331

{
  "id" : 5,
  "name" : "name",
  "subject" : "subject",
  "listId" : 5,
  "editorContentType" : "TEXT_HTML",
  "text" : "text",
  "html" : "html",
  "subscriptionMailingType" : "SUBSCRIPTION_VERIFICATION",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/subscription-mailings/5"
    }
  }
}

Mailing Approvals

Before a mailing can be sent it needs to be approved. Inxmail Professional offers the approval mechanism to distinguish between mailings that are still being worked on, and those where work is completed and verified. Typically a senior editor approves mailing to mark them as ready to be sent to the recipients.

The exact process of approval can be configured system wide or per list in the list properties. Depending on the used process a number of transitions could happen. The approvals endpoint allows to access a history of these events per mailing.

Furthermore the approvals endpoint allows to directly approve a given mailing. This is the fastest and most simple way to approve a mailing. More elaborated approval processes are currently not supported in this API.

Retrieve approval collection for a mailing

GET /mailings/{mailingId}/approvals

A GET request on the subscription mailing approvals resource will return the first page of mailing approvals.

Request parameters

Parameter Description

mailingId

The id of the related mailing.

Response structure

See section pagination.

The resources will have following response structure:

Path Type Description

id

Number

The id of this object.

mailingId

Number

The id of the related mailing.

username

String

Name of the user who caused the transition. May be null.

approvalComment

String

Comment for this transition. May be null.

entryDate

String

The point in time when this event occurred.

approvalStateTransition

String

A value describing the transition. See following table.

List of values for the approvalStateTransition field:

Value Description

REQUEST_APPROVAL

Approval process started according to configuration

DENY

A request for approval according to process is denied

APPROVED

Without approval process configured, Immediate approval

REVOKE_REQUEST

Approval process stopped before deadline or approval

ESCALATED

When the escalating approval process is configured, the first deadline is hit

DEADLINE

Final deadline hit, approval process aborted

DISABLED

Ongoing request for approval according to configuration aborted due to change in configuration

OVERRIDE

With approval process configured, immediate approval

INVALIDATE

Current approval revoked

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings/1/approvals' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1542

{
  "_embedded" : {
    "inx:approvals" : [ {
      "id" : 1,
      "approvalStateTransition" : "APPROVED",
      "mailingId" : 1,
      "entryDate" : "2024-11-19T08:47:36Z",
      "username" : "John Smith",
      "approvalComment" : "This mailing is approved.",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/approvals/1"
        }
      }
    }, {
      "id" : 2,
      "approvalStateTransition" : "INVALIDATE",
      "mailingId" : 1,
      "entryDate" : "2024-11-19T08:47:36Z",
      "username" : "John Smith",
      "approvalComment" : "This mailing is below standard.",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/approvals/2"
        }
      }
    }, {
      "id" : 3,
      "approvalStateTransition" : "ESCALATED",
      "mailingId" : 1,
      "entryDate" : "2024-11-19T08:47:36Z",
      "username" : null,
      "approvalComment" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/approvals/3"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/approvals?afterId=0&pageSize=3"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/approvals?afterId=3&pageSize=3"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Create an approval

Request structure

The following parameters are required to approve a mailing:

Path Type Description Constraints

approvalComment

String

A comment for the approval

approvalCommand

String

The command for the approval process. Must be "APPROVE" or "INVALIDATE"..

Response structure

The resources will return the url of the approval history in the self link:

{
  "id" : 123,
  "approvalId" : 123,
  "approvalComment" : "COMMENT",
  "approvalCommand" : "APPROVE",
  "approvalStateTransition" : null,
  "entryDate" : null,
  "userName" : null,
  "mailingId" : 1,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/approvals/123"
    }
  }
}

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings/1/approvals' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "approvalComment" : "COMMENT",
  "approvalCommand" : "APPROVE"
}'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/mailings/1/approvals/123
Content-Type: application/hal+json
Content-Length: 326

{
  "id" : 123,
  "approvalId" : 123,
  "approvalComment" : "COMMENT",
  "approvalCommand" : "APPROVE",
  "approvalStateTransition" : null,
  "entryDate" : null,
  "userName" : null,
  "mailingId" : 1,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/approvals/123"
    }
  }
}

Revoke a granted approval

Request structure

The following parameters are required to approve a mailing:

Path Type Description Constraints

approvalComment

String

A comment for the approval

approvalCommand

String

The command for the approval process. Must be "APPROVE" or "INVALIDATE".

Response structure

The resources will return the url of the approval history in the self link:

{
  "id" : 123,
  "approvalId" : 123,
  "approvalComment" : "COMMENT",
  "approvalCommand" : "INVALIDATE",
  "approvalStateTransition" : null,
  "entryDate" : null,
  "userName" : null,
  "mailingId" : 1,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/approvals/123"
    }
  }
}

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings/1/approvals' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "approvalComment" : "COMMENT",
  "approvalCommand" : "INVALIDATE"
}'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/mailings/1/approvals/123
Content-Type: application/hal+json
Content-Length: 329

{
  "id" : 123,
  "approvalId" : 123,
  "approvalComment" : "COMMENT",
  "approvalCommand" : "INVALIDATE",
  "approvalStateTransition" : null,
  "entryDate" : null,
  "userName" : null,
  "mailingId" : 1,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/approvals/123"
    }
  }
}

Mailing operations

The following mailing operations are available and can be used by invoking the mailing operations endpoint with the specific command.

POST /operations/mailings{?command}
Command Description

copy

Create a copy of a mailing

Copy mailing

A POST request with the copy command and the following payload structure will create a copy of a mailing. Violations of the constraints will lead to validation errors.

Payload structure

Path Type Description Constraints

mailingId

Number

The ID of the mailing to copy

  • Must not be null

copyApprovalState

Boolean

Optional: Copies the approval state of the source mailing.

listId

Number

Optional: The Id of the list into which the mailing should be copied to. The target list must be a list of type STANDARD or DYNAMIC.

name

String

Optional: The new name of the mailing’s copy.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/operations/mailings?command=copy' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "mailingId" : 2
}'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/mailings/50
Content-Type: application/hal+json
Content-Length: 1147

{
  "name" : "Copy of mailing name",
  "id" : 50,
  "type" : "REGULAR_MAILING",
  "listId" : 42,
  "creationDate" : "2024-11-19T08:47:43Z",
  "subject" : "Subject of the mailing",
  "modificationDate" : "2024-11-19T08:47:43Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/50"
    },
    "inx:renderedContent" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/50/renderedContent"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/42"
    },
    "inx:sendings" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings?mailingId=50"
    },
    "inx:clicks" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/clicks?mailingId=50"
    },
    "inx:web-beacon-hits" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?mailingId=50"
    },
    "inx:links" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/50/links"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

A link inside of a mailing does not only consist of an URL. A link is described as an object with properties like name or type. These link information will be used during mail rendering process to generate a specific html link.

Link type

The field type of the response defines the type of the link. It can be one of these values.

Link Type Description

COUNT

Tracking link that counts each click

UNIQUE_COUNT

Tracking link that counts only the first click of every recipient, subsequent clicks are still available

OPENING_COUNT

Trackable image that counts only the first loading for each recipient, subsequent openings are still available

UNSUBSCRIBE_LINK

Unsubscribes the current recipient without an additional verification step

UNSUBSCRIBE_PAGE

Unsubscribes the current recipient using a HTML landing page

UNSUBSCRIBE_FORM

Unsubscribes the current recipient using a landing page managed by Inxmail Professional

UNSUBSCRIBE_HEADER_LINK

Unsubscribes the current recipient using the List-Unsubscribe header. Clients which support this feature (like Google mail) will show an unsubscription button at the top of the mailing

VERIFY_SUBSCRIPTION

Verifies the subscription of the current recipient

VERIFY_UNSUBSCRIPTION

Verifies the unsubscription of the current recipient

GRANT_TRACKING_PERMISSION

Allows tracking of the current recipient

WITHDRAW_TRACKING_PERMISSION

Removes the tracking permission of the current recipient

REDIRECT

Can be used to perform actions before redirecting to the target URL

UNSUBSCRIBE

deprecated Use UNSUBSCRIBE_LINK, UNSUBSCRIBE_FORM, UNSUBSCRIBE_PAGE, UNSUBSCRIBE_HEADER_LINK instead

Unsubscribes the current recipient without an additional verification step

CONTENT_TRACKED

Tracking link embedded in external content e.g. content from a content-include (unique count)

CONTENT_OPENING

Trackable image embedded in external content e.g. content from a content-include (unique count)

Retrieve mailing links collection

GET /mailings/{id}/links{?types}

A GET request with an ID parameter will return the first page of the containing links. See section pagination.

Path parameters

Table 20. /customer/rest/v1/mailings/{id}/links
Parameter Description

id

The ID of the mailing containing these links

Request parameters

Parameter Required Description

types

no

The link type for the desired links. More than one value can be specified with multiple query parameters or comma separated list. Default is all link types. Possible values are: [REDIRECT, COUNT, UNIQUE_COUNT, CONTENT_TRACKED, UNSUBSCRIBE, UNSUBSCRIBE_LINK, UNSUBSCRIBE_FORM, UNSUBSCRIBE_PAGE, UNSUBSCRIBE_HEADER_LINK, VERIFY_SUBSCRIPTION, VERIFY_UNSUBSCRIPTION, CONTENT_OPENING, OPENING_COUNT, GRANT_TRACKING_PERMISSION, WITHDRAW_TRACKING_PERMISSION].

Response structure

See the sections response structure of a single link and pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings/42/links' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1322

{
  "_embedded" : {
    "inx:links" : [ {
      "name" : "HereBeUrl.alias",
      "id" : 1,
      "type" : "UNIQUE_COUNT",
      "url" : "https://herebeurl.invalid",
      "mailingId" : 42,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/links/1"
        }
      }
    }, {
      "name" : "HereBeUrl.alias",
      "id" : 2,
      "type" : "UNSUBSCRIBE_FORM",
      "url" : "https://herebeurl.invalid",
      "mailingId" : 42,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/links/2"
        }
      }
    }, {
      "name" : "HereBeUrl.alias",
      "id" : 3,
      "type" : "WITHDRAW_TRACKING_PERMISSION",
      "url" : "https://herebeurl.invalid",
      "mailingId" : 42,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/links/3"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/42/links?afterId=0&pageSize=3"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/42/links?afterId=3&pageSize=3"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve single link

GET /links/{id}

A GET request with an ID parameter will return the requested link.

Request structure

Table 21. /customer/rest/v1/links/{id}
Parameter Description

id

The ID of the link
Path Type Description

id

Number

The ID of the link

mailingId

Number

The ID of the mailing containing this link

url

String

The URL of the link

name

String

The name of this link

type

String

The type of this link

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/links/2' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 488

{
  "name" : "HereBeUrl.alias",
  "id" : 2,
  "type" : "UNSUBSCRIBE_FORM",
  "url" : "https://herebeurl.invalid",
  "mailingId" : 2,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/links/2"
    },
    "inx:mailing" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/2"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}
GET /links{?mailingIds,types}

A GET request without any parameters will return all links.

Request parameters

Parameter Required Description

mailingIds

no

The corresponding mailing ids for the desired links. More than one value can be specified with multiple query parameters or comma separated list.

types

no

The link types for the desired links. More than one value can be specified with multiple query parameters or comma separated list. Default is all link types. Possible values are: [REDIRECT, COUNT, UNIQUE_COUNT, CONTENT_TRACKED, UNSUBSCRIBE, UNSUBSCRIBE_LINK, UNSUBSCRIBE_FORM, UNSUBSCRIBE_PAGE, UNSUBSCRIBE_HEADER_LINK, VERIFY_SUBSCRIPTION, VERIFY_UNSUBSCRIPTION, CONTENT_OPENING, OPENING_COUNT, GRANT_TRACKING_PERMISSION, WITHDRAW_TRACKING_PERMISSION].

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/links?mailingIds=1,2&types=UNIQUE_COUNT,UNSUBSCRIBE_FORM,WITHDRAW_TRACKING_PERMISSION' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1621

{
  "_embedded" : {
    "inx:links" : [ {
      "name" : "HereBeUrl.alias",
      "id" : 1,
      "type" : "UNIQUE_COUNT",
      "url" : "https://herebeurl.invalid",
      "mailingId" : 1,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/links/1"
        },
        "inx:mailing" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1"
        }
      }
    }, {
      "name" : "HereBeUrl.alias",
      "id" : 2,
      "type" : "UNSUBSCRIBE_FORM",
      "url" : "https://herebeurl.invalid",
      "mailingId" : 2,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/links/2"
        },
        "inx:mailing" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/2"
        }
      }
    }, {
      "name" : "HereBeUrl.alias",
      "id" : 3,
      "type" : "WITHDRAW_TRACKING_PERMISSION",
      "url" : "https://herebeurl.invalid",
      "mailingId" : 2,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/links/3"
        },
        "inx:mailing" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/2"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/links?afterId=0&pageSize=1&mailingIds=1&mailingIds=2&types=UNIQUE_COUNT&types=UNSUBSCRIBE_FORM&types=WITHDRAW_TRACKING_PERMISSION"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Mailing rendered content

The rendered content of a mailing consists of multiple fields that describe the content of a mailing (subject, HTML part, etc.). By default the returned content of this resource will be personalized with a test recipient that only contains an email address as recipient data (unknown@unknown.invalid).

If the content contains links or embedded images the following rules applies: Standard links are fully functional, tracking links are functional but will not trigger any events or generate any clicks, unsubscription links will redirect but not unsubscribe anybody. Embedded images are replaced with http references to image resources on the Inxmail server.

Please note that the process of rendering a mailing can be rather expensive in terms of performance and also in the size of data returned in the response. Because of the latter the overall attachment size is limited to 500kB per mailing in this resource. If the limit is exceeded this resource will respond with a mailing-render-error problem response.

To calculate the size of the rendered content of a mailing, you can use the endpoint documented in Calculate size of rendered mailing content.

Retrieve single mailing rendered content

GET /mailings/{id}/renderedContent{?testProfileId,includeAttachments}

A GET request with a ID parameter will return the rendered content for the requested mailing.

Request structure

Table 22. /customer/rest/v1/mailings/{id}/renderedContent
Parameter Description

id

The ID of the mailing

Request parameters

Parameter Required Description

testProfileId

no

The ID of a specific test profile that will be used to render the mailing.

includeAttachments

no

If true, indicates that the attachments of the mailing are included in the result. Otherwise, no attachments are included.

Response structure

Path Type Description

subject

String

The rendered subject of the mailing

text

String

The rendered text part of the mailing

html

String

The rendered html part of the mailing

attachments

Array

The attachments of the mailing. Omitted if no attachments were requested with the 'includeAttachments' parameter

attachments[].fileName

String

The file name of the attachment

attachments[].contentType

String

The content type of the attachment

attachments[].data

String

The data of the attachment (base64 encoded)

_links

Object

Links to other resources

Example without attachments

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings/1/renderedContent' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 477

{
  "text" : "text content",
  "html" : "<html><h1>html content</h1></html>",
  "subject" : "subject",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/renderedContent"
    },
    "inx:mailing" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Example with attachments

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings/1/renderedContent?testProfileId=5&includeAttachments=true' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 649

{
  "text" : "text content",
  "html" : "<html><h1>html content</h1></html>",
  "subject" : "subject",
  "attachments" : [ {
    "fileName" : "invoice.pdf",
    "contentType" : "application/pdf",
    "data" : "SSBhbSBubyBwZGYh"
  } ],
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/renderedContent?testProfileId=5&includeAttachments=true"
    },
    "inx:mailing" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Calculate size of rendered mailing content

GET /mailings/{id}/rendered-content-size

A GET request with a mailing ID parameter will render the content of the requested mailing and then return the size of the rendered content. Please note that the size is being calculated based on a recipient-dummy, which can sometimes yield inaccurate results.

Response Body

{
  "renderedContentSize" : 1000,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/rendered-content-size"
    }
  }
}

The renderedContentSize field in the response contains the size of the rendered mailing in bytes.

Example

Curl-Request
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings/1/rendered-content-size' -i -X GET
HTTP-Request
GET /customer/rest/v1/mailings/1/rendered-content-size HTTP/1.1
Host: api.inxmail.com
HTTP-Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 166

{
  "renderedContentSize" : 1000,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/rendered-content-size"
    }
  }
}

HTTP Datasources

The datasources can be created as PDF or HTTP datasources. The data can then be used as text, text transformation or as a file attachment in an email. The API allows requesting HTTP datasources. Datasources of type PDF are currently not retrievable.

For the datasources, it can be defined when they should be queried during mailing dispatch. The following options are available:

  • Query the data source for each recipient (RECIPIENT_BASED).

  • Query the data source only once at the start of the mailing (ONCE).

  • Query the data source on demand and cache the content (RECIPIENT_CACHED).

Retrieve single HTTP datasource

GET /datasources/http/{id}

Request structure

The following path parameters are required:

Table 23. /customer/rest/v1/datasources/http/{id}
Parameter Description

id

The ID of the http datasource

Response structure

Path Type Description

name

String

The name of the http datasource.

id

Number

The ID of the http data source. PDF and FILE datasources cannot be requested.

contentEncoding

Null

The default value is UTF-8.

fetchStrategy

String

The value is "ONCE", if the content is static. If the content is cached, the value is "RECIPIENT_BASED". If the data source is requested again for each recipient, the value is "RECIPIENT_BASED".

attachmentFileName

String

The name of the file attachment that will be assigned if the option "attach as file attachment" was selected.

encodeUrlPlaceholders

Boolean

The value is true when the encode url placeholders were selected.

contentWithInxmailTags

Boolean

The value is true when inxmail tags were selected.

lastSaveDate

String

The date of the last saving.

url

String

The url of the http datasource.

useType

String

The use type specifies how the http datasource is used in emails.

_links

Object

Links to other resources

Example without attributes

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/datasources/http/1' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 446

{
  "name" : "Sample DataSource",
  "id" : 1,
  "url" : "www.sample.de",
  "fetchStrategy" : "ONCE",
  "attachmentFileName" : "SampleAttachmentFileName",
  "encodeUrlPlaceholders" : true,
  "useType" : "ATTACHMENT_FILE",
  "lastSaveDate" : "1970-01-17T16:01:15Z",
  "contentWithInxmailTags" : false,
  "contentEncoding" : null,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/datasources/http/1"
    }
  }
}

Retrieve HTTP datasource collection

GET /datasources/http

A GET request on the http datasources will return the first page of http datasources.

Response structure

See section pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/datasources/http' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1721

{
  "_embedded" : {
    "inx:datasources" : [ {
      "name" : "Sample Datasource_201",
      "id" : 201,
      "url" : "www.one.de",
      "fetchStrategy" : "ONCE",
      "attachmentFileName" : "File-One-Name",
      "encodeUrlPlaceholders" : true,
      "useType" : "ATTACHMENT_FILE",
      "lastSaveDate" : "1970-01-17T16:01:15Z",
      "contentWithInxmailTags" : false,
      "contentEncoding" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/datasources/http/201"
        }
      }
    }, {
      "name" : "Sample Datasource_202",
      "id" : 202,
      "fetchStrategy" : "RECIPIENT_CACHED",
      "encodeUrlPlaceholders" : false,
      "useType" : "TRANSFORMED_TEXT",
      "lastSaveDate" : "1970-01-17T16:01:15Z",
      "contentWithInxmailTags" : true,
      "contentEncoding" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/datasources/http/202"
        }
      }
    }, {
      "name" : "Sample Datasource_203",
      "id" : 203,
      "fetchStrategy" : "RECIPIENT_BASED",
      "encodeUrlPlaceholders" : true,
      "useType" : "TEXT",
      "lastSaveDate" : "1970-01-17T16:01:15Z",
      "contentWithInxmailTags" : true,
      "contentEncoding" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/datasources/http/203"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/datasources/http?afterId=0&pageSize=1"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Delete HTTP datasource

DELETE /datasources/http/{id}

A DELETE request with the following parameter will delete an existing http datasource: n.b. requesting a delete on a file or PDF datasource type is not possible.

Request structure

The following path parameters are required:

Table 24. /customer/rest/v1/datasources/http/{id}
Parameter Description

id

The ID of the http datasource to be deleted.

Response structure

HTTP/1.1 204 No Content

Create a HTTP datasource

POST /datasources/http

A POST request with the following request body will create a new http datasource:

Request structure

The following path parameters are required:

Path Type Description Constraints

name

String

The name of the http datasource.

url

String

The url of the http datasource.

attachmentFileName

String

The name of the file attached to this datasource

contentWithInxmailTags

Boolean

The value is true when inxmail tags were selected.

encodeUrlPlaceholders

Boolean

The value is true when the encode url placeholders were selected.

useType

String

The use type specifies how the http datasource is used in emails.

fetchStrategy

String

The value is "ONCE", if the content is static. If the content is cached, the value is "RECIPIENT_BASED". If the data source is requested again for each recipient, the value is "RECIPIENT_BASED".

Response structure

HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/datasources/http/0
Content-Type: application/hal+json
Content-Length: 366

{
  "id" : 0,
  "name" : "datasource name",
  "url" : "datasource.url",
  "useType" : "ATTACHMENT_FILE",
  "fetchStrategy" : "ONCE",
  "contentWithInxmailTags" : false,
  "encodeUrlPlaceholders" : false,
  "attachmentFileName" : "attachment name",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/datasources/http/0"
    }
  }
}

Update a HTTP datasource

PUT /datasources/http/{id}

A PUT request with the following request body will create a new http datasource:

Request structure

The following path parameters are required:

Path Type Description Constraints

name

String

The name of the http datasource.

  • Must not be null

  • Must not contain padding whitespace characters

  • Size must be between 1 and 255 inclusive

url

String

The url of the http datasource.

attachmentFileName

String

The name of the file attached to this datasource

contentWithInxmailTags

Boolean

The value is true when inxmail tags were selected.

encodeUrlPlaceholders

Boolean

The value is true when the encode url placeholders were selected.

useType

String

The use type specifies how the http datasource is used in emails.

fetchStrategy

String

The value is "ONCE", if the content is static. If the content is cached, the value is "RECIPIENT_BASED". If the data source is requested again for each recipient, the value is "RECIPIENT_BASED".

Response structure

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 442

{
  "name" : "thisNameIsNew",
  "id" : 0,
  "url" : "http://datasource.url",
  "fetchStrategy" : "RECIPIENT_BASED",
  "attachmentFileName" : "thisIsAnotherNewName",
  "encodeUrlPlaceholders" : false,
  "useType" : "ATTACHMENT_FILE",
  "lastSaveDate" : null,
  "contentWithInxmailTags" : false,
  "contentEncoding" : null,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/datasources/http/333"
    }
  }
}

Action Triggers

An action trigger defines the required parameters for an action event to be triggered.

Retrieve single action trigger

GET /actions/{id}

A GET request with a ID parameter will return the requested action trigger.

Request structure

GET /customer/rest/v1/actions/1 HTTP/1.1
Host: api.inxmail.com

Response structure

Path Type Description

id

Number

The ID of the action trigger

name

String

The name of the action trigger

description

String

The description of the action trigger

creationDate

String

The creation date of the trigger

modificationDate

String

The modification date of the trigger

listId

Number

The ID of the list associated to the action trigger.

actionTriggerType

String

The type of the action trigger

executeAlways

Boolean

Boolean Flag tells whether execute always or not. Used only for ON_CLICK actionTriggerType

actionSequence

Array

Collection of actionSequence items

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/actions/1' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 641

{
  "name" : "actionTrigger",
  "id" : 1,
  "description" : "This action triggers an event",
  "listId" : 76,
  "creationDate" : "2024-11-19T08:46:46Z",
  "actionTriggerType" : "ON_CLICK",
  "actionSequence" : [ ],
  "modificationDate" : "2024-11-19T08:46:46Z",
  "executeAlways" : false,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/actions/1"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/76"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve action trigger collection

GET /actions

A GET request on the action resource will return the first page of action triggers

Request structure

GET /customer/rest/v1/actions HTTP/1.1
Host: api.inxmail.com

Response structure

{
  "_embedded" : {
    "inx:actions" : [ {
      "name" : "actor",
      "id" : 1,
      "description" : "acts on a thing",
      "listId" : 2,
      "creationDate" : "2024-11-19T08:46:46Z",
      "actionTriggerType" : "ON_CLICK",
      "actionSequence" : [ ],
      "modificationDate" : "2024-11-19T08:46:46Z",
      "executeAlways" : false,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/actions/1"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/2"
        }
      }
    }, {
      "name" : "actionTrigger",
      "id" : 11,
      "description" : "trigger something",
      "listId" : 46,
      "creationDate" : "2024-11-19T08:46:46Z",
      "actionTriggerType" : "ON_CLICK",
      "actionSequence" : [ ],
      "modificationDate" : "2024-11-19T08:46:46Z",
      "executeAlways" : false,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/actions/11"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/46"
        }
      }
    }, {
      "name" : "ActionMan",
      "id" : 45,
      "description" : "a man of action",
      "listId" : 77,
      "creationDate" : "2024-11-19T08:46:46Z",
      "actionTriggerType" : "ON_CLICK",
      "actionSequence" : [ ],
      "modificationDate" : "2024-11-19T08:46:46Z",
      "executeAlways" : false,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/actions/45"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/77"
        }
      }
    }, {
      "name" : "actedup",
      "id" : 112,
      "description" : "acts upon stuff",
      "listId" : 23,
      "creationDate" : "2024-11-19T08:46:46Z",
      "actionTriggerType" : "ON_CLICK",
      "actionSequence" : [ ],
      "modificationDate" : "2024-11-19T08:46:46Z",
      "executeAlways" : false,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/actions/112"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/23"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/actions?afterId=0&pageSize=1"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/actions' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 2520

{
  "_embedded" : {
    "inx:actions" : [ {
      "name" : "actor",
      "id" : 1,
      "description" : "acts on a thing",
      "listId" : 2,
      "creationDate" : "2024-11-19T08:46:46Z",
      "actionTriggerType" : "ON_CLICK",
      "actionSequence" : [ ],
      "modificationDate" : "2024-11-19T08:46:46Z",
      "executeAlways" : false,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/actions/1"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/2"
        }
      }
    }, {
      "name" : "actionTrigger",
      "id" : 11,
      "description" : "trigger something",
      "listId" : 46,
      "creationDate" : "2024-11-19T08:46:46Z",
      "actionTriggerType" : "ON_CLICK",
      "actionSequence" : [ ],
      "modificationDate" : "2024-11-19T08:46:46Z",
      "executeAlways" : false,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/actions/11"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/46"
        }
      }
    }, {
      "name" : "ActionMan",
      "id" : 45,
      "description" : "a man of action",
      "listId" : 77,
      "creationDate" : "2024-11-19T08:46:46Z",
      "actionTriggerType" : "ON_CLICK",
      "actionSequence" : [ ],
      "modificationDate" : "2024-11-19T08:46:46Z",
      "executeAlways" : false,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/actions/45"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/77"
        }
      }
    }, {
      "name" : "actedup",
      "id" : 112,
      "description" : "acts upon stuff",
      "listId" : 23,
      "creationDate" : "2024-11-19T08:46:46Z",
      "actionTriggerType" : "ON_CLICK",
      "actionSequence" : [ ],
      "modificationDate" : "2024-11-19T08:46:46Z",
      "executeAlways" : false,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/actions/112"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/23"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/actions?afterId=0&pageSize=1"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Delete single action trigger

DELETE /actions/{id}

A DELETE request will remove action trigger and return statusCode=204. In case Action Trigger by specified id will not be found then response will have statusCode=404.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/actions/1' -i -X DELETE

Create single action trigger

POST /actions

A POST request will create action trigger and return statusCode=201. In case payload data is invalid then response will have statusCode=400.

Request structure

POST /customer/rest/v1/actions HTTP/1.1
Content-Type: application/hal+json
Content-Length: 419
Host: api.inxmail.com

{
  "name" : "actionTriggerName",
  "listId" : 3,
  "description" : "actionTriggerDescription",
  "actionTriggerType" : "ON_NEWSLETTER_SEND_EVENT",
  "executeAlways" : true,
  "actionSequence" : [ {
    "attributeId" : "16",
    "actionSequenceType" : "SET_VALUE_ACTION_TYPE",
    "value" : "=Date()"
  }, {
    "attributeId" : "10",
    "actionSequenceType" : "SET_VALUE_ACTION_TYPE",
    "value" : "SomeValue"
  } ]
}

Response structure

Path Type Description

id

Number

The ID of the action trigger

name

String

The name of the action trigger

description

String

The description of the action trigger

creationDate

String

The creation date of the trigger

modificationDate

String

The modification date of the trigger

listId

Number

The ID of the list associated to the action trigger.

actionTriggerType

String

The type of the action trigger

executeAlways

Boolean

Boolean Flag tells whether execute always or not. Used only for ON_CLICK actionTriggerType

actionSequence

Array

Collection of actionSequence items

actionSequence[0].attributeId

String

ActionSequence attributeId

actionSequence[0].value

String

ActionSequence value

actionSequence[0].actionSequenceType

String

ActionSequence actionSequenceType

actionSequence[0].orderId

String

ActionSequence orderId

actionSequence[1].attributeId

String

ActionSequence attributeId

actionSequence[1].actionSequenceType

String

ActionSequence actionSequenceType

actionSequence[1].orderId

String

ActionSequence orderId

actionSequence[1].value

String

ActionSequence value

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/actions' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "name" : "actionTriggerName",
  "listId" : 3,
  "description" : "actionTriggerDescription",
  "actionTriggerType" : "ON_NEWSLETTER_SEND_EVENT",
  "executeAlways" : true,
  "actionSequence" : [ {
    "attributeId" : "16",
    "actionSequenceType" : "SET_VALUE_ACTION_TYPE",
    "value" : "=Date()"
  }, {
    "attributeId" : "10",
    "actionSequenceType" : "SET_VALUE_ACTION_TYPE",
    "value" : "SomeValue"
  } ]
}'

Examples of ActionTriggerType:

  • ON_CLICK (boolean executeAlways is applied only to this type)

  • ON_NEWSLETTER_SEND_EVENT

  • ON_SINGLE_MAIL_SEND_EVENT

  • ON_HARD_BOUNCE

  • ON_SOFT_BOUNCE

  • ON_UNKNOWN_BOUNCE

  • ON_AUTO_RESPONDER_BOUNCE

  • ON_SPAM_BOUNCE

  • ON_AUTO_RESPONDER_REPLY

  • ON_FLAME_REPLY_TYPE

  • ON_UNKNOWN_REPLY_TYPE

  • ON_SPAM_REPLY_TYPE

  • ON_SUBSCRIBE_TYPE

  • ON_UNSUBSCRIBE_TYPE

  • ON_TRACKING_PERMISSION_GRANTED

  • ON_TRACKING_PERMISSION_DENIED

  • ON_NEWSLETTER_SEND_EVENT

  • ON_SINGLE_MAIL_SEND_EVENT

  • ON_HARD_BOUNCE

  • ON_SOFT_BOUNCE

  • ON_UNKNOWN_BOUNCE

  • ON_AUTO_RESPONDER_BOUNCE

  • ON_SPAM_BOUNCE

  • ON_AUTO_RESPONDER_REPLY

  • ON_FLAME_REPLY_TYPE

  • ON_UNKNOWN_REPLY_TYPE

  • ON_SPAM_REPLY_TYPE

  • ON_SUBSCRIBE_TYPE

  • ON_UNSUBSCRIBE_TYPE

  • ON_TRACKING_PERMISSION_GRANTED

  • ON_TRACKING_PERMISSION_DENIED

  • ON_NEWSLETTER_SEND_EVENT

  • ON_SINGLE_MAIL_SEND_EVENT

  • ON_HARD_BOUNCE

  • ON_SOFT_BOUNCE

  • ON_UNKNOWN_BOUNCE

  • ON_AUTO_RESPONDER_BOUNCE

  • ON_SPAM_BOUNCE

  • ON_AUTO_RESPONDER_REPLY

  • ON_FLAME_REPLY_TYPE

  • ON_UNKNOWN_REPLY_TYPE

  • ON_SPAM_REPLY_TYPE

  • ON_SUBSCRIBE_TYPE

  • ON_UNSUBSCRIBE_TYPE

  • ON_TRACKING_PERMISSION_GRANTED

  • ON_TRACKING_PERMISSION_DENIED

Examples of ActionSequence Request data based on actionSequenceType:

  • SET_VALUE_ACTION_TYPE

{
"actionSequenceType" : "SET_VALUE_ACTION_TYPE",
"attributeId" : "3",
"value" : "someValue"
}

  • SET_EXPR_ACTION_TYPE

{
"actionSequenceType" : "SET_EXPR_ACTION_TYPE",
"attributeId" : "3",
"expression" : "expressionValue"
}

  • ADD_VALUE_ACTION_TYPE

{
"actionSequenceType" : "ADD_VALUE_ACTION_TYPE",
"attributeId" : "3",
"value" : "someValue"
}

  • SEND_MAILING_ACTION_TYPE

{
"actionSequenceType" : "SEND_MAILING_ACTION_TYPE",
"listId" : "3",
"mailingId" : "4"
}

  • SEND_LAST_MAILING_ACTION_TYPE

{
"actionSequenceType" : "SEND_LAST_MAILING_ACTION_TYPE",
"listId" : "3"
}

  • SEND_ACTION_MAILING_ACTION_TYPE

{
"actionSequenceType" : "SEND_ACTION_MAILING_ACTION_TYPE",
"listId" : "3",
"actionMailingId" : "4"
}

  • DELETE_RECIPIENT_ACTION_TYPE

{
"actionSequenceType" : "DELETE_RECIPIENT_ACTION_TYPE",
"listId" : "3"
}

  • DELETE_RECIPIENT_FROM_ALL_LISTS_ACTION_TYPE

{
"actionSequenceType" : "DELETE_RECIPIENT_FROM_ALL_LISTS_ACTION_TYPE"
}

  • DELETE_RECIPIENT_FROM_SYSTEM_ACTION_TYPE

{
"actionSequenceType" : "DELETE_RECIPIENT_FROM_SYSTEM_ACTION_TYPE"
}

  • DIRECT_UNSUBSCRIBE_ACTION_TYPE

{
"actionSequenceType" : "DIRECT_UNSUBSCRIBE_ACTION_TYPE",
"listId" : "3"
}

  • AGENT_UNSUBSCRIBE_ACTION_TYPE

{
"actionSequenceType" : "AGENT_UNSUBSCRIBE_ACTION_TYPE",
"listId" : "3"
}

  • UNSUBSCRIBE_ALL_LISTS_ACTION_TYPE

{
"actionSequenceType" : "UNSUBSCRIBE_ALL_LISTS_ACTION_TYPE"
}

  • DIRECT_SUBSCRIBE_ACTION_TYPE

{
"actionSequenceType" : "DIRECT_SUBSCRIBE_ACTION_TYPE",
"listId" : "3"
}

  • AGENT_SUBSCRIBE_ACTION_TYPE

{
"actionSequenceType" : "AGENT_SUBSCRIBE_ACTION_TYPE",
"listId" : "3"
}

  • GRANT_TRACKING_PERMISSION_ACTION_TYPE

{
"actionSequenceType" : "GRANT_TRACKING_PERMISSION_ACTION_TYPE",
"listId" : "3"
}

  • REVOKE_TRACKING_PERMISSION_ACTION_TYPE

{
"actionSequenceType" : "REVOKE_TRACKING_PERMISSION_ACTION_TYPE",
"listId" : "3"
}

  • TRANSFER_TRACKING_PERMISSION_FROM_SELECTED_LIST

{
"actionSequenceType" : "TRANSFER_TRACKING_PERMISSION_FROM_SELECTED_LIST",
"listId" : "3",
"sourceListId" : "4"
}

Examples of ActionSequence Response data based on actionSequenceType:

  • SET_VALUE_ACTION_TYPE

{
"actionSequenceType" : "SET_VALUE_ACTION_TYPE",
"attributeId" : "3",
"value" : "someValue",
"orderId" : "1"
}

  • SET_EXPR_ACTION_TYPE

{
"actionSequenceType" : "SET_EXPR_ACTION_TYPE",
"attributeId" : "3",
"expression" : "expressionValue",
"orderId" : "1"
}

  • ADD_VALUE_ACTION_TYPE

{
"actionSequenceType" : "ADD_VALUE_ACTION_TYPE",
"attributeId" : "3",
"value" : "someValue",
"orderId" : "1"
}

  • SEND_MAILING_ACTION_TYPE

{
"actionSequenceType" : "SEND_MAILING_ACTION_TYPE",
"listId" : "3",
"mailingId" : "4",
"orderId" : "1"
}

  • SEND_LAST_MAILING_ACTION_TYPE

{
"actionSequenceType" : "SEND_LAST_MAILING_ACTION_TYPE",
"listId" : "3",
"orderId" : "1"
}

  • SEND_ACTION_MAILING_ACTION_TYPE

{
"actionSequenceType" : "SEND_ACTION_MAILING_ACTION_TYPE",
"listId" : "3",
"actionMailingId" : "4",
"orderId" : "1"
}

  • DELETE_RECIPIENT_ACTION_TYPE

{
"actionSequenceType" : "DELETE_RECIPIENT_ACTION_TYPE",
"listId" : "3",
"orderId" : "1"
}

  • DELETE_RECIPIENT_FROM_ALL_LISTS_ACTION_TYPE

{
"actionSequenceType" : "DELETE_RECIPIENT_FROM_ALL_LISTS_ACTION_TYPE",
"orderId" : "1"
}

  • DELETE_RECIPIENT_FROM_SYSTEM_ACTION_TYPE

{
"actionSequenceType" : "DELETE_RECIPIENT_FROM_SYSTEM_ACTION_TYPE",
"orderId" : "1"
}

  • DIRECT_UNSUBSCRIBE_ACTION_TYPE

{
"actionSequenceType" : "DIRECT_UNSUBSCRIBE_ACTION_TYPE",
"listId" : "3",
"orderId" : "1"
}

  • AGENT_UNSUBSCRIBE_ACTION_TYPE

{
"actionSequenceType" : "AGENT_UNSUBSCRIBE_ACTION_TYPE",
"listId" : "3",
"orderId" : "1"
}

  • UNSUBSCRIBE_ALL_LISTS_ACTION_TYPE

{
"actionSequenceType" : "UNSUBSCRIBE_ALL_LISTS_ACTION_TYPE",
"orderId" : "1"
}

  • DIRECT_SUBSCRIBE_ACTION_TYPE

{
"actionSequenceType" : "DIRECT_SUBSCRIBE_ACTION_TYPE",
"listId" : "3",
"orderId" : "1"
}

  • AGENT_SUBSCRIBE_ACTION_TYPE

{
"actionSequenceType" : "AGENT_SUBSCRIBE_ACTION_TYPE",
"listId" : "3",
"orderId" : "1"
}

  • GRANT_TRACKING_PERMISSION_ACTION_TYPE

{
"actionSequenceType" : "GRANT_TRACKING_PERMISSION_ACTION_TYPE",
"listId" : "3",
"orderId" : "1"
}

  • REVOKE_TRACKING_PERMISSION_ACTION_TYPE

{
"actionSequenceType" : "REVOKE_TRACKING_PERMISSION_ACTION_TYPE",
"listId" : "3",
"orderId" : "1"
}

  • TRANSFER_TRACKING_PERMISSION_FROM_SELECTED_LIST

{
"actionSequenceType" : "TRANSFER_TRACKING_PERMISSION_FROM_SELECTED_LIST",
"listId" : "3",
"sourceListId" : "4",
"orderId" : "1"
}

Update single action trigger

PUT /actions/1

A PUT request will update existing action trigger and return statusCode=200. In case payload data is invalid then response will have statusCode=400. In case there will be no existing ActionTrigger by provided id then response will have statusCode=404.

Request structure

PUT /customer/rest/v1/actions/1 HTTP/1.1
Content-Type: application/hal+json
Content-Length: 419
Host: api.inxmail.com

{
  "name" : "actionTriggerName",
  "listId" : 3,
  "description" : "actionTriggerDescription",
  "actionTriggerType" : "ON_NEWSLETTER_SEND_EVENT",
  "executeAlways" : true,
  "actionSequence" : [ {
    "attributeId" : "16",
    "actionSequenceType" : "SET_VALUE_ACTION_TYPE",
    "value" : "=Date()"
  }, {
    "attributeId" : "10",
    "actionSequenceType" : "SET_VALUE_ACTION_TYPE",
    "value" : "SomeValue"
  } ]
}

Response structure

Path Type Description

id

Number

The ID of the action trigger

name

String

The name of the action trigger

description

String

The description of the action trigger

creationDate

String

The creation date of the trigger

modificationDate

String

The last save date of the trigger

listId

Number

The ID of the list associated to the action trigger.

actionTriggerType

String

The type of the action trigger

executeAlways

Boolean

Boolean Flag tells whether execute always or not. Used only for ON_CLICK actionTriggerType

actionSequence

Array

Collection of actionSequence items

actionSequence[0].attributeId

String

ActionSequence attributeId

actionSequence[0].value

String

ActionSequence value

actionSequence[0].actionSequenceType

String

ActionSequence actionSequenceType

actionSequence[0].orderId

String

ActionSequence orderId

actionSequence[1].attributeId

String

ActionSequence attributeId

actionSequence[1].actionSequenceType

String

ActionSequence actionSequenceType

actionSequence[1].orderId

String

ActionSequence orderId

actionSequence[1].value

String

ActionSequence value

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/actions/1' -i -X PUT \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "name" : "actionTriggerName",
  "listId" : 3,
  "description" : "actionTriggerDescription",
  "actionTriggerType" : "ON_NEWSLETTER_SEND_EVENT",
  "executeAlways" : true,
  "actionSequence" : [ {
    "attributeId" : "16",
    "actionSequenceType" : "SET_VALUE_ACTION_TYPE",
    "value" : "=Date()"
  }, {
    "attributeId" : "10",
    "actionSequenceType" : "SET_VALUE_ACTION_TYPE",
    "value" : "SomeValue"
  } ]
}'

Sendings

A sending contains statistical information about the dispatch of a mailing to recipients. Information about the sending is available after the mailing has started to send. While typically regular mailings will only have one sending, it is possible for a regular mailing to have multiple sendings, see Regular Mailings. Trigger mailings are allowed multiple sendings.

The sending contains information about the following data:

  • list id of the mailing

  • mailing id

  • sending state (NOT_STARTED, PREPARED, SENDING, USER_INTERRUPTED, CRASHED, FINISHED),

  • start and end date of the sending,

  • last modification date of the sending

  • sending type (MASS_MAILING,SINGLE_MAILING,TIME_TRIGGER_MAILING, SPLIT_TEST_MAILING)

  • total size of the sending in bytes.

Retrieve single sending

GET /sendings/{id}

A GET request with an ID parameter will return the requested sending.

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/sendings/1' -i -X GET

Response structure

Path Type Description

id

Number

The ID of the sending

mailingId

Number

The ID of the mailing

listId

Number

The ID of the associated list

state

String

The state of the sending. Possible values are [NOT_STARTED, PREPARED, SENDING, USER_INTERRUPTED, CRASHED, FINISHED]

startDate

String

The start date of the sending

endDate

String

The end date of the sending

type

String

The type of the sending. Possible values are [MASS_MAILING, SINGLE_MAILING, TIME_TRIGGER_MAILING, SEQUENCE_MAILING, SPLIT_TEST_MAILING]

totalSize

Number

The total size of the sending

lastModificationDate

String

The last saved date of the sending

_links

Object

Links to other resources
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 698

{
  "state" : "FINISHED",
  "id" : 1,
  "type" : "MASS_MAILING",
  "listId" : 1,
  "endDate" : "2024-11-19T08:47:54Z",
  "mailingId" : 2,
  "startDate" : "2024-11-19T08:47:54Z",
  "lastModificationDate" : "2024-11-19T08:47:54Z",
  "totalSize" : 0,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings/1"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/1"
    },
    "inx:mailing" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/2"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve all sendings of all specified mailings

A mailing can have one or many sendings.

GET /sendings{?mailingId,sendingsFinishedBeforeDate,sendingsFinishedAfterDate,listIds}

A GET request with an ID parameter will return the sendings of the mailing.

Request structure

$ curl 'https://api.inxmail.com/customer/rest/v1/sendings?mailingId=1&sendingsFinishedBeforeDate=2024-11-19T08:47:54.673Z&sendingsFinishedAfterDate=2024-11-19T08:47:54.673Z&listIds=1' -i -X GET

Request parameters

Parameter Required Description

mailingId

no

The ID of the mailing to retrieve sendings for. Only one value at a time can be specified.

listIds

no

The IDs of the lists to retrieve sendings for.

sendingsFinishedBeforeDate

no

All sendings that were sent before this date (ISO 8601) will be returned. When this value is set, only sendings that have been sent before that given date (inclusive) will be included in the result.

sendingsFinishedAfterDate

no

All sendings that were sent after this date (ISO 8601) will be returned. When this value is set, only sendings that have been sent after that given date (exclusive) will be included in the result.
Note

Please note that both request parameters sendingsFinishedBeforeDate and sendingsFinishedAfterDate are not recommended to be used for continuous synchronisations. For continuous synchronisation use id-based requests to avoid problems of date based synchronization. For this purpose each time you reach the last page of a collection you find a link to next page you should request in your next scheduled synchronization. A possible problem of date based synchronization could be that most recent data is not yet available and would be missed if you request a specific date-time range. For further information please read: Long term data synchronization with the upcoming link.

Retrieve all sendings of multiple mailings and/or lists

It is possible to query sendings by a list of mailing IDs and a list of list IDs. Parameters mailingId and mailingIds cannot be used at the same time.

GET /sendings{?mailingIds,listIds,sendingsFinishedBeforeDate,sendingsFinishedAfterDate}

A GET request with an ID parameter will return the sendings of the mailing.

Request structure

$ curl 'https://api.inxmail.com/customer/rest/v1/sendings?mailingIds=1,2&listIds=1,2,3&sendingsFinishedBeforeDate=2024-11-19T08:47:54.806Z&sendingsFinishedAfterDate=2024-11-19T08:47:54.806Z' -i -X GET

Request parameters

Parameter Required Description

mailingIds

no

The IDs of the mailings to retrieve sendings for.

listIds

no

The IDs of the lists to retrieve sendings for.

sendingsFinishedBeforeDate

no

All sendings that were sent before this date (ISO 8601) will be returned. When this value is set, only sendings that have been sent before that given date (inclusive) will be included in the result.

sendingsFinishedAfterDate

no

All sendings that were sent after this date (ISO 8601) will be returned. When this value is set, only sendings that have been sent after that given date (exclusive) will be included in the result.

Retrieve sending details of a specific sending

It is possible to query sending details of a single sending. Sending details are e.g. the recipient count, the number of delivered mails and the number of not sent mails.

A GET request with an ID path parameter will return the details of the sending.

Request structure

$ curl 'https://api.inxmail.com/customer/rest/v1/sendings/1/details' -i -X GET

Response structure

Path Type Description

id

Number

The ID of the sending

recipientsCount

Number

The total number of recipients intended as recipients of the mailings. Subtract sentErrorCount and notSentMailsCount from this number to get the actual number of mails that has been sent out

rejectedCount

Number

The number of rejected mails (direct bounces)

bounceCount

Number

The sum of hard- and softbounces

notSentMailsCount

Number

The number of not sent mails because this recipent is affected by certain inxmail commands, like the nomail command (See Inxmail online help for more details).

deliveredMailsCount

Number

The number of delivered mails

sentErrorCount

Number

The number of sent errors, meaning an error occurred before the mail even was sent to a specific recipient, eg. a build process error happend.

_links

Object

Links to other resources
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 532

{
  "id" : 1,
  "recipientsCount" : 12,
  "rejectedCount" : 11,
  "bounceCount" : 1,
  "deliveredMailsCount" : 11,
  "sentErrorCount" : 0,
  "notSentMailsCount" : 1,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings/1/details"
    },
    "inx:sending" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings/1"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Send a single mailing / send/continue a mass mailing

POST /sendings

This functionality is only available for regular mailings.

A POST request with the following payload structure will send an already approved mailing as either:

  • a single specified recipient (Note: this also works if the mailing has already finished.)

  • a mass mailing to all recipients in the list associated with the mailing. (Note: if the mass mailing had been interrupted, it will resume sending. Finished mailings cannot be sent as a mass mailing again.)

Violations of the constraints will lead to validation errors.

Payload structure

Path Type Description Constraints

mailingId

Number

The ID of the mailing

  • Must not be null

recipientId

Number

The ID of the recipient the mailing should be sent to. Note: If null and if the state of the mailing is not finished,it will be sent as a mass mailing to all recipients in the list that is associated with the mailing.

Example (single mailing)

Request
POST /customer/rest/v1/sendings HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/hal+json
Content-Length: 43
Host: api.inxmail.com

{
  "mailingId" : 3,
  "recipientId" : 14
}
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/sendings/1
Content-Type: application/hal+json
Content-Length: 362

{
  "state" : "SENDING",
  "id" : 1,
  "type" : "SINGLE_MAILING",
  "listId" : 2,
  "endDate" : "2024-11-19T08:47:53Z",
  "mailingId" : 3,
  "startDate" : "2024-11-19T08:47:53Z",
  "lastModificationDate" : "2024-11-19T08:47:53Z",
  "totalSize" : 1234,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings/1"
    }
  }
}

Example (mass mailing)

Request
POST /customer/rest/v1/sendings HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/hal+json
Content-Length: 21
Host: api.inxmail.com

{
  "mailingId" : 3
}
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/sendings/1
Content-Type: application/hal+json
Content-Length: 360

{
  "state" : "SENDING",
  "id" : 1,
  "type" : "MASS_MAILING",
  "listId" : 2,
  "endDate" : "2024-11-19T08:47:53Z",
  "mailingId" : 3,
  "startDate" : "2024-11-19T08:47:53Z",
  "lastModificationDate" : "2024-11-19T08:47:53Z",
  "totalSize" : 1234,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings/1"
    }
  }
}

Sending Protocol

The sending protocol keeps track of all the recipients in a sending. For each recipient in a sending there is a sending protocol entry. You can find out which recipient received the mailing and which recipient did not receive it because of specific reasons, e.g. hardbounce.

Each sending protocol entry contains information about the following data:

  • recipient id

  • sending protocol state

Retrieve sending protocol collection

GET /sendings/{sendingId}/protocol

A GET request with a sending id on the sending protocol resource will return the first page of sending protocol entries.

Request structure

The following path parameters are required:

Table 25. /customer/rest/v1/sendings/{sendingId}/protocol
Parameter Description

sendingId

The Id of the sending

Request Parameters

Parameter Required Description

embedded

no

Indicates the relations of the resources that should be embedded in the result.

recipientAttributes

no

Indicates the names of the recipient attributes that should be included in the embedded recipient result. More than one value can be specified with multiple query parameters or comma separated list.

reactionData

no

Specifies whether the reaction data should be included in the response. The parameter should only be set if the data is actually needed, as it causes extra work and affects performance

Embeddable relations

Relation Description

inx:recipient

The recipient who clicked the link, if known.

Response structure

See section pagination.

The resources will have following response structure:

Path Type Description

state

String

The state of this recipient in this sending. Possible values are: NOT_SENT, SENT, RECIPIENT_NOT_FOUND, ERROR, ADDRESS_REJECTED, HARDBOUNCE, SOFTBOUNCE, UNKNOWNBOUNCE, SPAMBOUNCE, MUST_ATTRIBUTE, NO_MAIL

recipientId

Number

The ID of the recipient associated to this sending

clicked

Boolean

If the link was clicked by the recipient, null if no data is recorded, due to missing tracking permissions. Only included if the reactionData parameter is set to true.

opened

Boolean

If the link was opened by the recipient, null if no data is recorded, due to missing tracking permissions. Only included if the reactionData parameter is set to true.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/sendings/1/protocol?embedded=inx:recipient&recipientAttributes=firstName,lastName' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1043

{
  "_embedded" : {
    "inx:protocol-entries" : [ {
      "recipientId" : 3,
      "state" : "SENT"
    }, {
      "recipientId" : 4,
      "state" : "SENT",
      "_embedded" : {
        "inx:recipient" : {
          "id" : 123,
          "attributes" : {
            "firstName" : "John",
            "lastName" : "Doe"
          },
          "email" : "john.doe@example.com",
          "lowerEmail" : null,
          "unavailable" : false,
          "last_modified" : "2018-04-17T12:06:14Z",
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/recipients/123"
            }
          }
        }
      }
    }, {
      "recipientId" : 5,
      "state" : "SENT"
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings/1/protocol?pageSize=-1&embedded=inx%3Arecipient"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Recipient Attributes

Recipient attributes are used for storing information about the recipients. This information may be used for:

  • personalization of mailings

  • segmentation of recipients (target groups)

Inxmail Professional does not limit which or how many attributes can be created, although we advise not to create too many of them to prevent performance degradation.

The only limitation imposed on attributes are the available data types:

  • Text

  • Date with time

  • Date only

  • Time only

  • Integer

  • Float

  • Boolean

Text attributes are limited to 80 characters by default but can be configured to store up to 255 characters. They may contain any UTF-8 character, although we strongly recommend to restrict usage to the Basic Multilingual Plane (BMP).

A typical use case of date and time attributes is storing temporal information like the birthday of a recipient or the last time the recipient ordered something. For more information on the actual date format, see section Date/Time format and Timezone.

Integer attributes may be used to store integral numbers ranging from -2147483648 to 2147483647. Floating point attributes can store numbers ranging from 4.9E-324 to 1.7976931348623157E308 in double precision (64 bit).

Boolean attributes can store the values true and false only. Unset boolean attribute values are handled as false.

The name of a custom attribute must fulfill the following criteria:

  • The name must not be null

  • The name must not exceed 255 characters

  • The name does not consist of whitespace characters only

  • The name must not be email

  • The name must not begin with subscription_ (ignoring case)

  • The name must not begin with sequence_ (ignoring case)

  • The name must not begin with %

Retrieve single recipient attribute

GET /attributes/{id}

A GET request with an ID parameter will return the requested attribute.

Request structure

Table 26. /customer/rest/v1/attributes/{id}
Parameter Description

id

The ID of the resource

Response structure for non-text attributes

Path Type Description

id

Number

The ID of the resource

name

String

The name of the attribute.

type

String

The type of the attribute. Possible values: [DATE_AND_TIME, DATE_ONLY, TIME_ONLY, INTEGER, FLOATING_POINT_NUMBER, BOOLEAN]

creationDate

Null

The timestamp the attribute was created

modificationDate

Null

The timestamp the attribute was last updated

_links

Object

Links to other resources

Response structure for text attributes

Path Type Description

id

Number

The ID of the resource

name

String

The name of the attribute.

type

String

The type of the attribute. Will be 'TEXT' in this particular case.

maxLength

Number

The maximum length of the attribute value. Only applies to TEXT attributes.

creationDate

Null

The timestamp the attribute was created

modificationDate

Null

The timestamp the attribute was last updated

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/attributes/5' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 233

{
  "name" : "sample attribute",
  "id" : 5,
  "type" : "BOOLEAN",
  "creationDate" : null,
  "modificationDate" : null,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/attributes/5"
    }
  }
}

Retrieve recipient attributes collection

GET /attributes

A GET request on the attributes resource will return the first page of attributes.

'If-modified-since' HTTP Header

The header makes request conditional

  • if header not set, returns status code 200 and body with existing attributes. See section Response Structure.

  • if header set and attributes has not been modified since date, the response is a 304(not modified) without any body.

  • if header set, but attributes has no modification date at all, the response is a 304(not modified) without any body.

  • if header set and something has changed, returns status code 200 and body with existing attributes. See section Response Structure.

  • "Wed, 21 Oct 2015 07:28:00 GMT" date format is supported

  • ISO date format is supported (2020-08-25T12:25:34Z)

Request structure

GET /customer/rest/v1/attributes HTTP/1.1
If-modified-since: Wed, 21 Feb 2024 07:28:00 GMT
Host: api.inxmail.com

Response structure

See section pagination.

Note that the embedded resources may include both non-text attributes and text attributes in their particular default representation.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/attributes' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1272

{
  "_embedded" : {
    "inx:attributes" : [ {
      "name" : "Boolean",
      "id" : 3,
      "type" : "BOOLEAN",
      "creationDate" : null,
      "modificationDate" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/attributes/3"
        }
      }
    }, {
      "maxLength" : 80,
      "name" : "Text",
      "id" : 2,
      "type" : "TEXT",
      "creationDate" : null,
      "modificationDate" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/attributes/2"
        }
      }
    }, {
      "name" : "Integer",
      "id" : 5,
      "type" : "INTEGER",
      "creationDate" : null,
      "modificationDate" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/attributes/5"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/attributes?afterId=0&pageSize=3"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/attributes?afterId=5&pageSize=3"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Create recipient attribute

POST /attributes{?hidden}

A POST request with the following payload structure will create a new recipient attribute. Violations of the constraints will lead to validation errors.

Request parameters

Parameter Required Description

hidden

no

Defines the initial visibility of the new attribute in the Inxmail Professional GUI Client. Only applies to lists other than the system mailing list. true by default.

Payload structure

Path Type Description Constraints

name

String

The name of the new attribute

  • Must not be null

  • Must not contain padding whitespace characters

  • Size must be between 1 and 255 inclusive

type

String

The data type of the new attribute

  • Must be one of TEXT, DATE_AND_TIME, DATE_ONLY, TIME_ONLY, INTEGER, FLOATING_POINT_NUMBER, BOOLEAN

  • Must not be null

maxLength

Number

The mandatory maximum length of an attribute with type TEXT. Do not provide for attributes with other data types.

  • Must be at least 1

  • Must be at most 255

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/attributes?hidden=false' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "name" : "surename",
  "type" : "TEXT",
  "maxLength" : 30
}'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/attributes/5
Content-Type: application/hal+json
Content-Length: 242

{
  "maxLength" : 30,
  "name" : "surename",
  "id" : 5,
  "type" : "TEXT",
  "creationDate" : null,
  "modificationDate" : null,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/attributes/5"
    }
  }
}

Delete a recipient attribute

DELETE /attributes/{id}

A DELETE request with an ID parameter will delete the requested recipient attribute.

Please note: internal non-recipient attributes cannot be deleted. Such requests will receive status code 400.

Request structure

Table 27. /customer/rest/v1/attributes/{id}
Parameter Description

id

The ID of the recipient-attribute.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/attributes/26' -i -X DELETE
Response
HTTP/1.1 204 No Content

Recipients

Recipients are essentially the human beings or organizations you wish to contact with a mailing. Therefore, the most important information a recipient record holds, is the email address.

A recipient can be a member of multiple mailing lists, either by subscribing to them (which is the case for standard lists) or by fulfilling the segmentation criteria of a dynamic list. For more information regarding lists, see chapter Mailing lists.

In order to personalize the mailing content and to build target groups, recipient records can hold additional information in the form of recipient attributes. These attributes are common to all recipient records, while the values of course vary. For more information regarding recipient attributes, see chapter Recipient Attributes.

As it is not guaranteed that a recipient can be reached via the email address stored in Inxmail Professional, there also exists the concept of bounces. Bounces, put simply, are the mails sent by mail daemons and SMTP servers when a mail could not be delivered to the recipient. When this occurs, the recipient is marked as unreachable in Inxmail Professional and will not be contacted from that moment on, regardless of list membership.

Retrieve single recipient

GET /recipients/{id}{?attributes,allAttributes,trackingPermissionsForLists,subscriptionDatesForLists,unsubscriptionDatesForLists}

A GET request with an ID parameter will return the requested recipient.

Without additional parameters, we only return the id, the email and the unavailable flag of the requested recipient, not the attributes or the tracking permissions of the recipient. This is due to possible performance issues which could occur when there are a lot of attributes or tracking permissions available. However, there is the possibility to request specific attributes and even all attributes of a recipient. Is is also possible to request the tracking permissions of a recipient.

Request structure

The following path parameters are required:

Table 28. /customer/rest/v1/recipients/{id}
Parameter Description

id

The ID of the resource

Request parameters

Parameter Required Description

attributes

no

Indicates the names of the attributes that should be included in the result. More than one value can be specified with multiple query parameters or comma separated list. Ignored when allAttributes is true.

allAttributes

no

If true, indicates that all attributes of the recipient should be included in the result. Otherwise, no attributes are included. This parameter takes precedence over the attributes parameter.

trackingPermissionsForLists

no

Indicates the ids of the lists for which the tracking permissions should be included in the result. The specified lists must be of type STANDARD.

subscriptionDatesForLists

no

Indicates the ids of the lists for which the subscription dates should be included in the result. The specified lists must be of type STANDARD. This parameter cannot be specified simultaneously to the parameter unsubscriptionDatesForLists.

unsubscriptionDatesForLists

no

Indicates the ids of the lists for which the unsubscription dates should be included in the result. The specified lists must be of type STANDARD. If present, only the latest unsubscription date of the recipient on each requested list will be returned. This parameter cannot be specified simultaneously to the parameter unsubscriptionDatesForLists N.b. A full history of unsubscription dates for a specific recipient and list cannot be requested

Response structure

Path Type Description

id

Number

The ID of the resource

email

String

The email address of the recipient.

lowerEmail

String

The normalized (lower case) email address of the recipient.

last_modified

String

Indicates the date on which a recipient was updated for the last time. The date is presented in ISO 8601 format.

unavailable

Boolean

The bounce status of the recipient. If there are three or more hard bounces, the recipient is marked as unavailable. If true, mailings cannot be delivered to that recipient.

attributes

Object

The attributes of the recipient. Omitted if no attributes were requested or the recipient has no values for the requested attributes.

tracking-permissions

Array

The tracking permissions of the recipient. Omitted if the trackingPermissionsForLists parameter is not included in the request.

subscriptionDates

Array

The subscription dates of the recipient. Omitted if the subscriptionDatesForLists parameter is not included in the request.

unsubscriptionDates

Array

The unsubscription date of the recipient. Omitted if the unsubscriptionDatesForLists parameter is not included in the request.

_links

Object

Links to other resources

Example without attributes

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 272

{
  "id" : 5,
  "email" : "john.doe@example.com",
  "lowerEmail" : "john.doe@example.com",
  "unavailable" : false,
  "last_modified" : "2018-01-16T12:42:32Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5"
    }
  }
}

Example with selected attributes

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5?attributes=givenName&attributes=familyName' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 381

{
  "id" : 5,
  "attributes" : {
    "givenName" : "John",
    "familyName" : "Doe"
  },
  "email" : "john.doe@example.com",
  "lowerEmail" : "john.doe@example.com",
  "unavailable" : false,
  "last_modified" : "2018-01-16T12:42:32Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5?attributes=familyName%2CgivenName"
    }
  }
}

Example with all attributes

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5?allAttributes=true' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 366

{
  "id" : 5,
  "attributes" : {
    "givenName" : "John",
    "familyName" : "Doe"
  },
  "email" : "john.doe@example.com",
  "lowerEmail" : "john.doe@example.com",
  "unavailable" : false,
  "last_modified" : "2018-01-16T12:42:32Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5?allAttributes=true"
    }
  }
}

Example with tracking permissions

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5?trackingPermissionsForLists=8,15,17' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 487

{
  "id" : 5,
  "email" : "john.doe@example.com",
  "lowerEmail" : null,
  "unavailable" : false,
  "tracking-permissions" : [ {
    "listId" : 8,
    "permission" : "GRANTED"
  }, {
    "listId" : 15,
    "permission" : "DENIED"
  }, {
    "listId" : 17,
    "permission" : "DENIED"
  } ],
  "last_modified" : "2018-01-16T12:42:32Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5?trackingPermissionsForLists=8%2C15%2C17"
    }
  }
}

Example with subscription dates

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5?subscriptionDatesForLists=8,15,17' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 505

{
  "id" : 5,
  "email" : "john.doe@example.com",
  "lowerEmail" : null,
  "unavailable" : false,
  "subscriptionDates" : [ {
    "listId" : 8,
    "date" : "2018-01-16T12:42:32Z"
  }, {
    "listId" : 15,
    "date" : "2018-01-16T12:42:32Z"
  }, {
    "listId" : 17,
    "date" : "2018-01-16T12:42:32Z"
  } ],
  "last_modified" : "2018-01-16T12:42:32Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5?subscriptionDatesForLists=8%2C15%2C17"
    }
  }
}

Example with unsubscription dates

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5?unsubscriptionDatesForLists=8,15,17' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 509

{
  "id" : 5,
  "email" : "john.doe@example.com",
  "lowerEmail" : null,
  "unavailable" : false,
  "unsubscriptionDates" : [ {
    "listId" : 8,
    "date" : "2018-01-16T12:42:32Z"
  }, {
    "listId" : 15,
    "date" : "2018-01-16T12:42:32Z"
  }, {
    "listId" : 17,
    "date" : "2018-01-16T12:42:32Z"
  } ],
  "last_modified" : "2018-01-16T12:42:32Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5?unsubscriptionDatesForLists=8%2C15%2C17"
    }
  }
}

Example with completeRecipientInformation

If completeRecipientInformation is set, the request is treated as if allAttributes is set subscriptionDatesForLists is set for all lists the recipient is subscribed to unsubscriptionDatesForLists is set for all lists the recipient is unsubscribed from trackingPermissionsForLists is set for all lists where a trackingpermission is given¹ The trackingPermissionsForLists behavior is different from the existing flag, since we don’t explicitely return non-existing permissions as false Using completeRecipientInformation combined with any of the existing flags allAttributes subscriptionDatesForLists unsubscriptionDatesForLists trackingPermissionsForLists results in a HTTP 400

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5?completeRecipientInformation=true' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 652

{
  "id" : 5,
  "attributes" : {
    "givenName" : "John",
    "familyName" : "Doe"
  },
  "email" : "john.doe@example.com",
  "lowerEmail" : "john.doe@example.com",
  "unavailable" : false,
  "tracking-permissions" : [ {
    "listId" : 100,
    "permission" : "GRANTED"
  } ],
  "unsubscriptionDates" : [ {
    "listId" : 100,
    "date" : "1970-01-01T00:00:01Z"
  } ],
  "subscriptionDates" : [ {
    "listId" : 100,
    "date" : "1970-01-01T00:00:01Z"
  } ],
  "last_modified" : "2018-01-16T12:42:32Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5?completeRecipientInformation=true"
    }
  }
}

Retrieve recipients collection

GET /recipients{?attributes,subscribedTo,lastModifiedSince,email,attributes.attributeName,trackingPermissionsForLists,subscriptionDatesForLists,unsubscriptionDatesForLists,filterId,emailContainsIgnoreCase,attributesContainsIgnoreCase.someAttribute}

or

GET /recipients{?attributes,unsubscribedFrom,lastModifiedSince,email,attributes.attributeName,trackingPermissionsForLists}

A GET request on the recipients resource will return the first page of recipients.

Request parameters

Parameter Required Description

attributes

no

Indicates the names of the attributes that should be included in the result. More than one value can be specified with multiple query parameters or comma separated list.

subscribedTo

no

When set to the ID of an existing list, retrieves only recipients subscribed to that list. Warning: Retrieving recipients of dynamic lists can cause longer running times because the target group has to be evaluated. This parameter cannot be specified simultaneously to the parameter unsubscribedFrom.

subscribedToAny

no

When set to the IDs of existing standard lists, retrieves only recipients subscribed to that lists. Warning: Retrieving recipients of dynamic lists can cause longer running times because the target group has to be evaluated. This parameter cannot be specified simultaneously to the parameter unsubscribedFrom and subscribedTo.

unsubscribedFrom

no

When set to the ID of an existing list, retrieves only recipients unsubscribed from that list. Warning: Retrieving recipients of dynamic lists can cause longer running times because the target group has to be evaluated. This parameter cannot be specified simultaneously to the parameter subscribedTo.

unsubscribedFromAny

no

When set to the IDs of existing standard lists, retrieves only recipients unsubscribed from that lists. Warning: Retrieving recipients of dynamic lists can cause longer running times because the target group has to be evaluated. This parameter cannot be specified simultaneously to the parameter subscribedTo and unsubscribedFrom.

lastModifiedSince

no

Indicates the date (ISO 8601) on which a recipient was updated for the last time. When this value is set, only recipients which where updated since (inclusive) that given date will be included in the result. Only one value can be specified at the same time.

email

no

The email address of a recipient. When this value is set, only recipients with the given email address will be included in the result. More than one value can be specified with multiple query parameters or comma separated list.

attributes.attributeName

no

A wildcard query parameter where 'attributeName' is the name of a recipient attribute. This parameter can be used to filter recipients by their respective attributes. For example, the query attributes.familyName=Doe will return all recipients whose family name is Doe. The specified attribute has to exist and must be a custom user attribute. FLOATING_POINT_NUMBER attributes are currently not supported due to the imprecise nature of floating point numbers which inhibits a meaningful comparison for equality. TIME_ONLY attributes are also not supported at this point. Please also note, that the data type of the matching value (e.g. Doe) has to match the data type of the attribute. This parameter can be used for an arbitrary number of attributes (e.g. attributes.givenName=John&attributes.familyName=Doe).

trackingPermissionsForLists

no

Indicates the ids of the lists for which the tracking permissions should be included in the result. The specified lists must be of type STANDARD.

subscriptionDatesForLists

no

Indicates the ids of the lists for which the subscription dates should be included in the result. The specified lists must be of type STANDARD. This parameter cannot be specified simultaneously to the parameter unsubscriptionDatesForLists.

unsubscriptionDatesForLists

no

Indicates the ids of the lists for which the unsubscription dates should be included in the result. The specified lists must be of type STANDARD. If present, only the latest unsubscription date of the recipient on each requested list will be returned. This parameter cannot be specified simultaneously to the parameter unsubscriptionDatesForLists N.b. A full history of unsubscription dates for a specific recipient and list cannot be requested

filterId

no

When set to the ID of an target group, retrieves only recipients included in the specified groups conditions.

unavailable

no

The bounce flag of the recipient. Unavailable recipients have bounced and are not included in sending of mailing

emailContainsIgnoreCase

no

Allows finding of all recipients where email contains a specific string. Case insensitive

attributesContainsIgnoreCase.someAttribute

no

A wildcard query parameter where 'someAttribute' is the name of a recipient attribute. This parameter can be used to filter recipients by their respective attributes. For example:

Success query

Returns all recipients whose family name contains any case insensitive match of Doe

attributesContainsIgnoreCase.familyName=Doe

Returns all recipients whose family name contains any case insensitive match of Doe and last name contains any case insensitive match of LastNameValue

attributesContainsIgnoreCase.familyName=Doe&attributesContainsIgnoreCase.lastName=LastNameValue

Can be combined with attributes filter.

attributes.lastName=ExampleLstName&attributesContainsIgnoreCase.familyName=Doe

Failed query

Same key for attributes and attributesContainsIgnoreCase can not be used. Status code 400

attributes.lastName=ExampleLstName&attributesContainsIgnoreCase.lastName=Doe

Same key for attributesContainsIgnoreCase. Status code 400

attributesContainsIgnoreCase.lastName=ExampleLstName&attributesContainsIgnoreCase.lastName=Doe

Response structure

See section pagination.

Example without request parameters

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1047

{
  "_embedded" : {
    "inx:recipients" : [ {
      "id" : 5,
      "email" : "john.doe@example.com",
      "lowerEmail" : null,
      "unavailable" : false,
      "last_modified" : "2018-01-16T12:42:32Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5"
        }
      }
    }, {
      "id" : 15,
      "email" : "jane.doe@example.com",
      "lowerEmail" : null,
      "unavailable" : false,
      "last_modified" : "2018-01-16T11:42:32Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/15"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients?afterId=0&pageSize=2"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients?afterId=15&pageSize=2"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Example with selected attributes and subscribedTo

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients?attributes=familyName&attributes=givenName&subscribedTo=10' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1347

{
  "_embedded" : {
    "inx:recipients" : [ {
      "id" : 5,
      "attributes" : {
        "givenName" : "John",
        "familyName" : "Doe"
      },
      "email" : "john.doe@example.com",
      "lowerEmail" : null,
      "unavailable" : false,
      "last_modified" : "2018-01-16T12:42:32Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5"
        }
      }
    }, {
      "id" : 15,
      "attributes" : {
        "givenName" : "Jane",
        "familyName" : "Doe"
      },
      "email" : "jane.doe@example.com",
      "lowerEmail" : null,
      "unavailable" : false,
      "last_modified" : "2018-01-16T11:42:32Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/15"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients?afterId=0&pageSize=2&attributes=familyName&attributes=givenName&subscribedTo=10"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients?afterId=15&pageSize=2&attributes=familyName&attributes=givenName&subscribedTo=10"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Example with selected attributes and unsubscribedFrom

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients?attributes=familyName&attributes=givenName&unsubscribedFrom=10' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1355

{
  "_embedded" : {
    "inx:recipients" : [ {
      "id" : 5,
      "attributes" : {
        "givenName" : "John",
        "familyName" : "Doe"
      },
      "email" : "john.doe@example.com",
      "lowerEmail" : null,
      "unavailable" : false,
      "last_modified" : "2018-01-16T12:42:32Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5"
        }
      }
    }, {
      "id" : 15,
      "attributes" : {
        "givenName" : "Jane",
        "familyName" : "Doe"
      },
      "email" : "jane.doe@example.com",
      "lowerEmail" : null,
      "unavailable" : false,
      "last_modified" : "2018-01-16T11:42:32Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/15"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients?afterId=0&pageSize=2&attributes=familyName&attributes=givenName&unsubscribedFrom=10"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients?afterId=15&pageSize=2&attributes=familyName&attributes=givenName&unsubscribedFrom=10"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Example with selected email address

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients?email=john.doe@example.com' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 802

{
  "_embedded" : {
    "inx:recipients" : [ {
      "id" : 5,
      "email" : "john.doe@example.com",
      "lowerEmail" : null,
      "unavailable" : false,
      "last_modified" : "2018-01-16T12:42:32Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients?afterId=0&pageSize=1&email=john.doe%40example.com"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients?afterId=5&pageSize=1&email=john.doe%40example.com"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Example with given last modification date

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients?lastModifiedSince=2018-01-16T11:42:32Z' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1133

{
  "_embedded" : {
    "inx:recipients" : [ {
      "id" : 5,
      "email" : "john.doe@example.com",
      "lowerEmail" : null,
      "unavailable" : false,
      "last_modified" : "2018-01-16T12:42:32Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5"
        }
      }
    }, {
      "id" : 15,
      "email" : "jane.doe@example.com",
      "lowerEmail" : null,
      "unavailable" : false,
      "last_modified" : "2018-01-16T11:42:32Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/15"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients?afterId=0&pageSize=2&lastModifiedSince=2018-01-16T11%3A42%3A32Z"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients?afterId=15&pageSize=2&lastModifiedSince=2018-01-16T11%3A42%3A32Z"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Example with attribute filter

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients?attributes=givenName&attributes=familyName&attributes.familyName=Doe' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1185

{
  "_embedded" : {
    "inx:recipients" : [ {
      "id" : 5,
      "attributes" : {
        "givenName" : "John",
        "familyName" : "Doe"
      },
      "email" : "john.doe@example.com",
      "lowerEmail" : null,
      "unavailable" : false,
      "last_modified" : "2018-01-16T12:42:32Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5"
        }
      }
    }, {
      "id" : 15,
      "attributes" : {
        "givenName" : "Jane",
        "familyName" : "Doe"
      },
      "email" : "jane.doe@example.com",
      "lowerEmail" : null,
      "unavailable" : false,
      "last_modified" : "2018-01-16T11:42:32Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/15"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients?afterId=0&pageSize=1&attributes=givenName&attributes=familyName&attributes.familyName=Doe"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Example with selected trackingPermissionsForLists

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients?trackingPermissionsForLists=3&trackingPermissionsForLists=4&trackingPermissionsForLists=5' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1434

{
  "_embedded" : {
    "inx:recipients" : [ {
      "id" : 5,
      "email" : "john.doe@example.com",
      "lowerEmail" : null,
      "unavailable" : false,
      "tracking-permissions" : [ {
        "listId" : 3,
        "permission" : "GRANTED"
      }, {
        "listId" : 4,
        "permission" : "DENIED"
      }, {
        "listId" : 5,
        "permission" : "GRANTED"
      } ],
      "last_modified" : "2018-01-16T12:42:32Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5"
        }
      }
    }, {
      "id" : 15,
      "email" : "jane.doe@example.com",
      "lowerEmail" : null,
      "unavailable" : false,
      "tracking-permissions" : [ {
        "listId" : 3,
        "permission" : "DENIED"
      }, {
        "listId" : 4,
        "permission" : "DENIED"
      }, {
        "listId" : 5,
        "permission" : "DENIED"
      } ],
      "last_modified" : "2018-01-16T11:42:32Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/15"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients?afterId=0&pageSize=1&trackingPermissionsForLists=3%2C4%2C5"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Example with target group filter (filterId)

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients?filterId=1' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1175

{
  "_embedded" : {
    "inx:recipients" : [ {
      "id" : 5,
      "email" : "john.doe@example.com",
      "lowerEmail" : null,
      "unavailable" : false,
      "last_modified" : "2018-01-16T12:42:32Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5"
        }
      }
    }, {
      "id" : 15,
      "email" : "jane.doe@example.com",
      "lowerEmail" : null,
      "unavailable" : false,
      "last_modified" : "2018-01-16T11:42:32Z",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/15"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients?pageSize=-1&filterId=1"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients?pageSize=-1&filterId=1"
    },
    "first" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients?afterId=0&pageSize=-1&filterId=1"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Delete recipient

DELETE /recipients/{id}

A DELETE request with an ID parameter will delete the requested recipient from the system.

Request structure

The following path parameters are required:

Table 29. /customer/rest/v1/recipients/{id}
Parameter Description

id

The ID of the resource

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5' -i -X DELETE
Response
HTTP/1.1 204 No Content

Delete recipient from list

DELETE /lists/{id}/recipient/{recipientId}{?deleteUnsubscribed}

A DELETE request will delete the specified recipient from the specified list.

Request structure

The following path parameters are required:

Table 30. /customer/rest/v1/lists/{id}/recipient/{recipientId}
Parameter Description

id

The ID of the list for which the recipient should be deleted. The target list must not be a list of type SYSTEM.

recipientId

The ID of the recipient which should be deleted from a list.

deleteUnsubscribed

The query parameter is optional (default value is false). In case true allows the deletion from both tabs, subscribed and unsubscribed. In case false allows the deletion only from subscribed tab

 
DELETE /customer/rest/v1/lists/2/recipient/3?deleteUnsubscribed=true HTTP/1.1
Host: api.inxmail.com

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/lists/2/recipient/3?deleteUnsubscribed=true' -i -X DELETE
Response
HTTP/1.1 204 No Content

Patching a recipient

PATCH /recipients/{id}

or

PATCH /recipients/{email}

A PATCH request with the following payload structure will replace the specified fields with the respective values. Violations of the constraints will lead to validation errors.

Please note, that for patching it is possible to address the recipient by either the recipient id or the unique email address.

The patch format in use is application/merge-patch+json which is standardized by RFC 7396. The basic rules of merge-patch are as follows:

  • Missing fields are ignored, their values will remain the same

  • Fields with non-null values will be replaced with the given value

  • Fields with null values will remove the value of the given field

In the context of patching a recipient, there are two exceptions to these rules, as stated in the payload structure description:

  • The email field must not be null, as a recipient must always have an email address

  • The attributes field must not be null to prevent all attributes from being removed

It is still possible to omit these fields. You can, for example, just update certain attributes without changing the email address of the recipient.

Please note, that the response to a PATCH request will always contain all attributes to enable you to check the consistency of the patched recipient.

Payload structure

Path Type Description Constraints

email

String

The new email address

  • Must be a valid email address

  • Must not be null

attributes

Object

Object containing the attributes to change

  • Must not be null

Example by ID

Response to initial GET request
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 366

{
  "id" : 5,
  "attributes" : {
    "givenName" : "John",
    "familyName" : "Doe"
  },
  "email" : "john.doe@example.com",
  "lowerEmail" : "john.doe@example.com",
  "unavailable" : false,
  "last_modified" : "2018-01-16T12:42:32Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5?allAttributes=true"
    }
  }
}
Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5' -i -X PATCH \
    -H 'Content-Type: application/merge-patch+json' \
    -d '{
  "email" : "j.doe@example.com",
  "attributes" : {
    "givenName" : "Jonathan"
  }
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 349

{
  "id" : 5,
  "attributes" : {
    "givenName" : "Jonathan",
    "familyName" : "Doe"
  },
  "email" : "j.doe@example.com",
  "lowerEmail" : null,
  "unavailable" : false,
  "last_modified" : "2018-07-30T16:12:23Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5?allAttributes=true"
    }
  }
}

Example by email address

Response to initial GET request
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 366

{
  "id" : 5,
  "attributes" : {
    "givenName" : "John",
    "familyName" : "Doe"
  },
  "email" : "john.doe@example.com",
  "lowerEmail" : "john.doe@example.com",
  "unavailable" : false,
  "last_modified" : "2018-01-16T12:42:32Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5?allAttributes=true"
    }
  }
}
Request
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/john.doe@example.com' -i -X PATCH \
    -H 'Content-Type: application/merge-patch+json' \
    -d '{
  "email" : "j.doe@example.com",
  "attributes" : {
    "givenName" : "Jonathan"
  }
}'
Response
HTTP/1.1 200 OK
Content-Disposition: inline;filename=f.txt
Content-Type: application/hal+json
Content-Length: 349

{
  "id" : 5,
  "attributes" : {
    "givenName" : "Jonathan",
    "familyName" : "Doe"
  },
  "email" : "j.doe@example.com",
  "lowerEmail" : null,
  "unavailable" : false,
  "last_modified" : "2018-07-30T16:12:23Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5?allAttributes=true"
    }
  }
}

Creating a new Recipient

POST /recipients

A POST request with the payload structure as described here will create a new recipient on the global recipient list with the specified fields and the respective values. Violations of the constraints will lead to validation errors.

The email field must not be null, as a recipient must always have an email address. If the email address already exists, the recipient will not be created or otherwise changed. The attributes field must not be null.

The rules for attributes is as follows:

  • Missing fields are ignored, their values will be null

  • Fields with non-null values will be replaced with the given value

  • Fields with null values will have the value null

  • The data types in the attribute list must match the set data type of the existing attribute.

  • If a validation error occurs, the recipient will not be created.

Payload structure

Path Type Description Constraints

email

String

The email address of the new recipient

  • Must be a valid email address

  • Must not be null

attributes

Object

Object containing the recipient attributes. Attributes must already exist.

  • Must not be null

Response structure

See here.

Please note, that the response to a POST request will not include the attribute list. To get the attribute list, you may use the id in the given response and make a GET request as described here.

Example

Request
POST /customer/rest/v1/recipients/ HTTP/1.1
Content-Type: application/json
Content-Length: 246
Host: api.inxmail.com

{
  "attributes" : {
    "date" : "2022-04-03",
    "datetime" : "2022-04-03T14:33:00",
    "bool" : false,
    "text" : "Attribute with type text",
    "time" : "14:33:00",
    "float" : 3.14,
    "int" : 3
  },
  "email" : "j.doe@example.com"
}
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/recipients/4
Content-Type: application/hal+json
Content-Length: 266

{
  "id" : 4,
  "email" : "j.doe@example.com",
  "lowerEmail" : "j.doe@example.com",
  "unavailable" : false,
  "last_modified" : "2023-04-05T13:20:48Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/4"
    }
  }
}

Test profiles

A test profile represents recipient data that can be used to render a mailing without relying on the data of real recipients. They are usually used to verify the rendering output or to render a mailing for archiving purposes with a specific set of data.

Depending on its type it can be used only in a specific list (LIST) or in all lists (GLOBAL) to render a mailing.

Test profile type

Every test profile has one of the following types:

Test profile type Description

GLOBAL

Used for test profiles that are defined in the system list

LIST

Used for test profiles that are defined in a specific list

Retrieve single test profile

GET /test-profiles/{id}{?allAttributes}

A GET request with an ID parameter will return the requested test profile. It’s also possible to retrieve all user attributes with the allAttributes flag.

Request structure

Table 31. /customer/rest/v1/test-profiles/{id}
Parameter Description

id

The ID of the test profile

Response structure

Path Type Description

id

Number

The ID of the test profile

description

String

The description of the test profile

trackingPermission

Boolean

The tracking permission of the test profile

email

String

The email address of the test profile

type

String

The type of the test profile. Possible types are: [GLOBAL, LIST].

listId

Number

The ID of the list holding the test profile. Omitted for test profiles with type GLOBAL.

modificationDate

String

The modification date of this test profile

attributes

Object

The attributes of the test recipient. Omitted if no attributes were requested.

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/test-profiles/1?allAttributes=true' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 625

{
  "id" : 1,
  "type" : "LIST",
  "attributes" : {
    "name" : "value"
  },
  "description" : "test profile description",
  "listId" : 12,
  "email" : "test@email.de",
  "modificationDate" : "2018-08-18T10:33:02Z",
  "trackingPermission" : true,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/test-profiles/1?allAttributes=true"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/12"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve test profile collection

GET /test-profiles{?listIds,types,allAttributes}

A GET request on the test profile resource will return the first page of test profiles.

Request parameters

Parameter Required Description

listIds

no

The IDs of the lists to retrieve test profiles for. More than one value can be specified with multiple query parameters or comma separated list. Default is all listIds.

allAttributes

no

If true, indicates that all attributes of the test-recipient should be included in the result. Otherwise, no attributes are included.

types

no

The test profile type for the desired test profiles. More than one value can be specified with multiple query parameters or comma separated list. Default is all test profile types. Possible values are: ${TestProfileType.values()}.

Response structure

See section pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/test-profiles' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 2073

{
  "_embedded" : {
    "inx:test-profiles" : [ {
      "id" : 1,
      "type" : "GLOBAL",
      "description" : "test profile 1 description",
      "email" : null,
      "modificationDate" : "2024-11-19T08:48:02Z",
      "trackingPermission" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/test-profiles/1"
        }
      }
    }, {
      "id" : 2,
      "type" : "GLOBAL",
      "description" : "test profile 2 description",
      "email" : null,
      "modificationDate" : "2024-11-19T08:48:02Z",
      "trackingPermission" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/test-profiles/2"
        }
      }
    }, {
      "id" : 3,
      "type" : "LIST",
      "description" : "test profile 3 description",
      "listId" : 2,
      "email" : null,
      "modificationDate" : "2024-11-19T08:48:02Z",
      "trackingPermission" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/test-profiles/3"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/2"
        }
      }
    }, {
      "id" : 4,
      "type" : "LIST",
      "description" : "test profile 4 description",
      "listId" : 3,
      "email" : null,
      "modificationDate" : "2024-11-19T08:48:02Z",
      "trackingPermission" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/test-profiles/4"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/test-profiles?afterId=0&pageSize=4"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/test-profiles?afterId=4&pageSize=4"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Create a test profile

A POST request on the test profile resource will create a new test profile. The parameter attributes is a map of strings containing the user attributes.

POST /test-profiles
POST /customer/rest/v1/test-profiles/ HTTP/1.1
Content-Type: application/hal+json
Content-Length: 162
Host: api.inxmail.com

{
  "listId" : 2,
  "email" : "test@test.invalid",
  "trackingPermission" : true,
  "attributes" : {
    "Vorname" : "Hugo"
  },
  "description" : "Description"
}

A successful response has the http return code 201 (created).

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/test-profiles/' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "listId" : 2,
  "email" : "test@test.invalid",
  "trackingPermission" : true,
  "attributes" : {
    "Vorname" : "Hugo"
  },
  "description" : "Description"
}'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/test-profiles/1
Content-Type: application/hal+json
Content-Length: 277

{
  "listId" : 2,
  "description" : "Description",
  "email" : "test@test.invalid",
  "trackingPermission" : true,
  "attributes" : {
    "Vorname" : "Hugo"
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/test-profiles/1"
    }
  }
}

Update a test profile

A PATCH request on the test profile resource will update a test profile. The parameter attributes is a map of strings containing the user attributes.

PATCH /test-profiles/1
PATCH /customer/rest/v1/test-profiles/1 HTTP/1.1
Content-Type: application/merge-patch+json
Content-Length: 146
Host: api.inxmail.com

{
  "email" : "test@test.invalid",
  "trackingPermission" : true,
  "attributes" : {
    "Vorname" : "Hugo"
  },
  "description" : "Description"
}

A successful response has the http return code 200.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/test-profiles/1' -i -X PATCH \
    -H 'Content-Type: application/merge-patch+json' \
    -d '{
  "email" : "test@test.invalid",
  "trackingPermission" : true,
  "attributes" : {
    "Vorname" : "Hugo"
  },
  "description" : "Description"
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 355

{
  "id" : 1,
  "type" : null,
  "attributes" : {
    "Vorname" : "Hugo"
  },
  "description" : "Description",
  "listId" : 2,
  "email" : "test@test.invalid",
  "modificationDate" : null,
  "trackingPermission" : true,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/test-profiles/1?allAttributes=false"
    }
  }
}

Delete a test profile

A DELETE request with an id url parameter will delete the test profile with that id.

DELETE /test-profiles/1
DELETE /customer/rest/v1/test-profiles/1 HTTP/1.1
Host: api.inxmail.com

A successful response has the http return code 204.

Example

Curl request
$ curl 'https://api.inxmail.com/customer/rest/v1/test-profiles/1' -i -X DELETE
HTTP request
DELETE /customer/rest/v1/test-profiles/1 HTTP/1.1
Host: api.inxmail.com
Response
HTTP/1.1 204 No Content

Memberships

A membership represents the connection between a recipient and a mailing list. When recipients are subscribed to a mailing list they are members of that list.

Delete all subscribed memberships of a mailing list

DELETE /memberships{?listId,state,recipientAttributes.attributeName}

A DELETE request with a given list ID and the state parameter of SUBSCRIBED will delete all members from that list. Both parameters must be set and the value of the state parameter must be SUBSCRIBED or the request will fail.

Request parameters

Parameter Required Description

listId

yes

The ID of the list for which all memberships should be deleted. The target list must be a list of type STANDARD.

state

yes

The state of the memberships to be deleted. At the moment SUBSCRIBED is the only supported state.

recipientAttributes.attributeName

no

A wildcard query parameter where 'attributeName' is the name of a recipient attribute. This parameter can be used to filter recipients by their respective attributes. For example, the query recipientAttributes.familyName=Doe will delete all recipients where the value of the attribute familyName equals Doe. The specified attribute has to exist and must be a custom user attribute. FLOATING_POINT_NUMBER attributes are currently not supported due to the imprecise nature of floating point numbers which inhibits a meaningful comparison for equality. TIME_ONLY attributes are also not supported at this point. Please also note, that the data type of the matching value (e.g. Doe) has to match the data type of the attribute. This parameter can be used for an arbitrary number of attributes (e.g. recipientAttributes.givenName=John&recipientAttributes.familyName=Doe).

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/memberships?listId=5&state=SUBSCRIBED&recipientAttributes.attributeName=John' -i -X DELETE
Response
HTTP/1.1 204 No Content

Add/Remove Recipient to List

This endpoint handles membership operations like subscribing or unsubscribing a recipient from a mailing list.

Request parameters

Parameter Required Description

command

yes

The command which should be executed. Must be 'listmembership'.

Payload structure

Path Type Description Constraints

recipientId

Number

The ID of the recipient the operation should be performed on.

  • Must be at least 1

  • Must not be null

listId

Number

The ID of the list the operation should be performed on.

  • Must be at least 1

  • Must not be null

action

String

The action which should be performed on the given list and recipient.

  • Must be one of ADD_TO_SUBSCRIBED, ADD_TO_UNSUBSCRIBED, REMOVE_FROM_LIST, RESUBSCRIBE, UNSUBSCRIBE

  • Must not be null

useOriginalSubscriptionDateIfPresent

Boolean

Whether the original application date should be reused, if present. If false the current date will be set. For actions of type ADD_TO_SUBSCRIBED and RESUBSCRIBE it is mandatory, for other actions it is ignored if specified.
Supported Actions
Action Description

ADD_TO_SUBSCRIBED

Adds the recipient to subscribed tab in the list and remove him from unsubscribed, if not already subscribed.

ADD_TO_UNSUBSCRIBED

Adds the recipient to unsubscribed tab in the list and removes him from subscribed, if not already unsubscribed.

REMOVE_FROM_LIST

Removes the recipient from the list.

RESUBSCRIBE

Subscribes the recipient to the list and removes him from unsubscribed, if he is in the unsubscribed tab.

UNSUBSCRIBE

Unsubscribes the recipient from the list and removes him from subscribed, if he is in the subscribed tab.

Response structure

Path Type Description

recipientId

Number

The ID of the recipient the operation should be performed on.

listId

Number

The ID of the list the operation should be performed on.

action

String

The action which should be performed on the given list and recipient.

useOriginalSubscriptionDateIfPresent

Boolean

Whether the original application date should be reused, if present. If false the current date will be set. For actions of type ADD_TO_SUBSCRIBED and RESUBSCRIBE it is mandatory, for other actions it is ignored if specified.

newState

String

The new state of the membership. One of: UNSUBSCRIBED, SUBSCRIBED, NOT_PRESENT.

_links

Object

Links to other resources
Supported newStates
newState Description

SUBSCRIBED

The recipient is now subscribed to the list.

UNSUBSCRIBED

The recipient is now unsubscribed from the list.

NOT_PRESENT

The recipient is now not present in the list.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/memberships/operations?command=listmembership' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "recipientId" : 1,
  "listId" : 2,
  "action" : "ADD_TO_SUBSCRIBED",
  "useOriginalSubscriptionDateIfPresent" : true
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 296

{
  "listId" : 2,
  "recipientId" : 1,
  "action" : "ADD_TO_SUBSCRIBED",
  "useOriginalSubscriptionDateIfPresent" : true,
  "newState" : "SUBSCRIBED",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/memberships/operations?command=listmembership"
    }
  }
}

Recipient subscriptions

Recipients can be subscribed to a mailing list via this API by creating a subscription event. This event will trigger the subscription mechanism which will produce a chain of events, representing the progress of the subscription. The latest event in the chain represents the current subscription status.

A subscription event can either be a successful subscription, a pending subscription (i.e. a subscription waiting for confirmation by the recipient) or a failed subscription. In the latter case, the event conveys the problem which caused the subscription to fail.

Event types

Every subscription event has one of the following types:

Event type Successful Description

PENDING_SUBSCRIPTION

Yes

A double opt-in subscription was triggered, the subscription still has to be confirmed

PENDING_SUBSCRIPTION_DONE

Yes

The recipient has confirmed the subscription and therefore is now subscribed to the specified list

VERIFIED_SUBSCRIPTION

Yes

The recipient has successfully been subscribed

MANUAL_SUBSCRIPTION

Yes

The recipient has successfully been subscribed by a user of the Inxmail Professional client application (1)

DUPLICATE_SUBSCRIPTION

Yes

Indicates that the recipient was already subscribed to the list specified in the request and has now been successfully resubscribed. Existing attributes are being overwritten by the ones provided in the request.

SUBSCRIPTION_TIMED_OUT

No

The recipient did not confirm the subscription in the configured time period

SUBSCRIPTION_ID_NOT_VALID

No

The confirmation could not be matched to the subscription request

SUBSCRIPTION_EMAIL_MISSMATCH

No

The confirmation could not be matched to the subscription request

BLACKLISTED

No

The subscription request was rejected because the email address of the recipient matches a blacklist entry

INVALID_ADDRESS_ERROR

No

The email address of the recipient to subscribe is not valid

SUBSCRIPTION_VERIFICATION_BOUNCED

No

The confirmation email sent to the recipient caused a bounce

SUBSCRIPTION_INTERNAL_ERROR

No

An internal error caused the subscription request to fail

LISTBOMBING_ATTEMPT

No

The anti list bombing service rejected the subscription request

(1) This includes the following actions in the Inxmail Professional Client.

  • Explicitly subscribing a recipient, that is present in the unsubscribed tab of that list. The 'resubscribe' function must be used.

  • Performing a manual 'force subscription' on a recipient, that is in a double opt in process and has not yet confirmed their subscription.

Adding a recipient through the recipient table does not constitute a manual subscription at the moment.

Retrieving a subscription event

GET /events/subscriptions/{id}

A GET request with an ID parameter will return the requested event.

Request structure

Table 32. /customer/rest/v1/events/subscriptions/{id}
Parameter Description

id

The ID of the event

Response structure

Path Type Description

id

Number

The ID of the event

type

String

The type of the event

listId

Number

The ID of the list associated to this event

recipientId

Number

The ID of the recipient associated to this event. Currently always null.

timestamp

String

The point in time when this event occurred

source

String

An identifier for the source which caused this event

emailAddress

String

The email address of the recipient associated to this event

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/events/subscriptions/3' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 777

{
  "id" : 3,
  "type" : "PENDING_SUBSCRIPTION_DONE",
  "listId" : 5,
  "recipientId" : 7,
  "timestamp" : "2024-11-19T08:47:21Z",
  "source" : "Your Integration",
  "emailAddress" : "john.doe@example.com",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/events/subscriptions/3"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/5"
    },
    "inx:recipient" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/7"
    },
    "prev" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/events/subscriptions/12"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve subscription event collection

GET /events/subscriptions{?listId,startDate,endDate,types,embedded,recipientAttributes}

A GET request on the subscription events resource will return the first page of subscription events.

Request parameters

Parameter Required Description

listId

no

The ID of the list to retrieve events for

listIds

no

The IDs of the lists to retrieve events for

startDate

no

The start date (inclusive) for the desired subscriptions

endDate

no

The end date (exclusive) for the desired subscriptions

types

no

The types for the desired subscriptions. Default is all types.

embedded

no

Indicates the relations of the resources that should be embedded in the result.

recipientAttributes

no

Indicates the names of the recipient attributes that should be included in the embedded recipient result. More than one value can be specified with multiple query parameters or comma separated list.

Embeddable relations

Relation Description

inx:recipient

The recipient who was subscribed. Since an email address written in different capitalization isessentially the same, it is possible that the capitalization of an email of a subscription event might differ from the capitalization of the related recipient.

Response structure

See section pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/events/subscriptions?listId=5&startDate=2024-11-19T07:47:22Z&endDate=2024-11-19T09:47:22Z&types=PENDING_SUBSCRIPTION,PENDING_SUBSCRIPTION_DONE&embedded=inx:recipient&recipientAttributes=firstName,lastName' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 2954

{
  "_embedded" : {
    "inx:subscription-events" : [ {
      "id" : 1,
      "type" : "PENDING_SUBSCRIPTION",
      "listId" : 3,
      "recipientId" : 5,
      "timestamp" : "2024-11-19T08:47:22Z",
      "source" : "Your Integration",
      "emailAddress" : "email@example.com",
      "_embedded" : {
        "inx:recipient" : {
          "id" : 7,
          "attributes" : {
            "firstName" : "Emma",
            "lastName" : "Mueller"
          },
          "email" : "email@example.com",
          "lowerEmail" : null,
          "unavailable" : false,
          "last_modified" : "2024-11-19T08:47:22Z",
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/recipients/7?attributes=firstName%2ClastName"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/events/subscriptions/1"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        },
        "inx:recipient" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5"
        }
      }
    }, {
      "id" : 2,
      "type" : "PENDING_SUBSCRIPTION_DONE",
      "listId" : 3,
      "recipientId" : 5,
      "timestamp" : "2024-11-19T08:47:22Z",
      "source" : "Subscription confirmation",
      "emailAddress" : "email@example.com",
      "_embedded" : {
        "inx:recipient" : {
          "id" : 7,
          "attributes" : {
            "firstName" : "Emma",
            "lastName" : "Mueller"
          },
          "email" : "email@example.com",
          "lowerEmail" : null,
          "unavailable" : false,
          "last_modified" : "2024-11-19T08:47:22Z",
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/recipients/7?attributes=firstName%2ClastName"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/events/subscriptions/2"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        },
        "inx:recipient" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5"
        },
        "prev" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/events/subscriptions/1"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/events/subscriptions?pageSize=-1&listIds=5&startDate=2024-11-19T07%3A47%3A22Z&endDate=2024-11-19T09%3A47%3A22Z&types=PENDING_SUBSCRIPTION&types=PENDING_SUBSCRIPTION_DONE&embedded=inx%3Arecipient&recipientAttributes=firstName&recipientAttributes=lastName"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Subscribing a recipient to a list

POST /events/subscriptions

A POST request with the following payload structure will initiate the subscription process for the specified recipient and list. Violations of the constraints will lead to validation errors. Furthermore, the provided listId must correspond to an existing standard mailing list and the specified email must not match a blacklist entry.

If there is a field named trackingPermission in the payload the content will be interpreted to set the recipient’s tracking permission. The value GRANTED (case insensitive matching) sets the permission to track this recipient. If the field is missing or an empty value is given the tracking permission of the recipient will not be changed. All other values will be interpreted as no permission to track this recipient.

In order to take advantage of Inxmail’s inhouse anti-listbombing service, it is required to include the 'suppliedRemoteAddress' attribute in the queries payload. If this field is not included or left valueless, the API will be unable to determine if the IP belongs to the actual potential attacker or simply to the integration.

The provided attributes must fulfill the following conditions:

  • The given attribute must already exist

  • The format of the attribute value must be correct

If one of these conditions is not fulfilled, the recipient will neither be subscribed nor created.

When creating attributes with the REST API, you have to use the following json data types for each attribute data type:

Table 33. Attribute data types to JSON data types
Attribute data type JSON data Type JSON Example

Text

String

"attributes":{"firstName": "John"}

Date with time

String

"attributes":{"date with time": "2016-02-04T10:30:12Z"}

Date only

String

"attributes":{"date": "2016-02-04"}

Time only

String

"attributes":{"time": "10:30:12Z"}

Integer

Integer

"attributes":{"age": 42}

Float

Float

"attributes":{"height": 3.14}

Boolean

Boolean

"attributes":{"male": true}

Note that, for Boolean attributes, empty values like null or "" will be handled as false.

Overwriting of attributes can be configured in the Subscriptions agent. If overwriting is allowed, provided attributes will overwrite existing ones while omitted attributes will remain the same.

The response will contain the resulting event type.

Payload structure

Path Type Description Constraints

listId

Number

The ID of the list the recipient shall be subscribed to

  • Must not be null

email

String

The email address of the recipient to subscribe

  • Must be a valid email address

  • Must not be null

trackingPermission

String

The tracking permission of the recipient.

attributes

Object

The attributes of the recipient.

source

String

An identifier for the source which caused this event.

suppliedRemoteAddress

String

The actual IP address of the subscription request.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/events/subscriptions/' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "listId" : 5,
  "email" : "john.doe@example.com",
  "attributes" : {
    "firstName" : "John",
    "age" : 42
  },
  "trackingPermission" : "GRANTED",
  "source" : "Your Integration",
  "suppliedRemoteAddress" : "108.0.0.9"
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 39

{
  "result" : "PENDING_SUBSCRIPTION"
}

Recipient unsubscriptions

Recipients can be unsubscribed from a mailing list via this API by creating an unsubscription event. This event will trigger the unsubscription mechanism which will produce a chain of events, representing the progress of the unsubscription. The latest event in the chain represents the current unsubscription status.

An usubscription event can either be a successful unsubscription, a pending unsubscription (i.e. a unsubscription waiting for confirmation by the recipient) or a failed unsubscription. In the latter case, the event conveys the problem which caused the unsubscription to fail.

Event types

Every unsubscription event has one of the following types:

Event type Successful Description

PENDING_UNSUBSCRIPTION

Yes

A double opt-out unsubscription was triggered, the unsubscription still has to be confirmed

PENDING_UNSUBSCRIPTION_DONE

Yes

The recipient has confirmed the unsubscription and therefore is now unsubscribed from the specified list

VERIFIED_UNSUBSCRIPTION

Yes

The recipient has successfully been unsubscribed

MANUAL_UNSUBSCRIPTION

Yes

The recipient has successfully been unsubscribed by a user of the Inxmail Professional client application (1)

DUPLICATE_UNSUBSCRIPTION

No

The recipient was already unsubscribed from the list specified in the request

UNSUBSCRIPTION_TIMED_OUT

No

The recipient did not confirm the unsubscription in the configured time period

UNSUBSCRIPTION_ID_NOT_VALID

No

The confirmation could not be matched to the unsubscription request

UNSUBSCRIPTION_EMAIL_MISSMATCH

No

The confirmation could not be matched to the unsubscription request

UNSUBSCRIPTION_VERIFICATION_BOUNCED

No

The confirmation email sent to the recipient caused a bounce

UNSUBSCRIPTION_INTERNAL_ERROR

No

An internal error caused the unsubscription request to fail

LIST_UNSUBSCRIBE_HEADER_UNSUBSCRIPTION

Yes

The recipient has successfully been unsubscribed through a list unsubscribe header link.

NOT_IN_SYSTEM_UNSUBSCRIPTION

No

No successful unsubscription, because the recipient is not known to the system.

NOT_IN_LIST_UNSUBSCRIPTION

No

No successful unsubscription, because the recipient is not a member of the list (neither subscribed nor unsubscribed).

(1) This includes the following actions in the Inxmail Professional Client.

  • Explicitly unsubscribing a recipient, that is present in the subscribed tab of that list. The 'unsubscribe' function must be used.

  • Performing a manual 'force unsubscription' on a recipient, that is in a double opt out process and has not yet confirmed their unsubscription.

Deleting a recipient through the recipient table does not constitute a manual unsubscription at the moment.

Please note: If the setting "Enable unsubscription of deleted recipients" is enabled for the target list, recipients can be unsubscribed from that list although they are neither subscribed nor unsubscribed from that list. The resulting event type will be suffixed with '_NOT_IN_LIST' to indicate this special case. If this setting ist not enabled, an unsubscription of a recipient who is not subscribed to the target list will result in the event type 'NOT_IN_LIST_UNSUBSCRIPTION':

Event type Successful Description

LIST_UNSUBSCRIBE_HEADER_UNSUBSCRIPTION_NOT_IN_LIST

Yes

Successful unsubscription through a list unsubscribe header link where the recipient is not a member of the list (neither subscribed nor unsubscribed).

PENDING_UNSUBSCRIPTION_NOT_IN_LIST

Yes

Unconfirmed pending unsubscription where the recipient is not a member of the list (neither subscribed nor unsubscribed).

PENDING_UNSUBSCRIPTION_DONE_NOT_IN_LIST

Yes

Confirmed and successful pending unsubscription where the recipient is not a member of the list (neither subscribed nor unsubscribed).

VERIFIED_UNSUBSCRIPTION_NOT_IN_LIST

Yes

Verified and successful unsubscription from a list where the recipient is not a member of the list (neither subscribed nor unsubscribed).

Retrieving an unsubscription event

GET /events/unsubscriptions/{id}

A GET request with an ID parameter will return the requested event.

Request structure

Table 34. /customer/rest/v1/events/unsubscriptions/{id}
Parameter Description

id

The ID of the event

Response structure

Path Type Description

id

Number

The ID of the event

type

String

The type of the event

listId

Number

The ID of the list associated to this event

recipientId

Number

The ID of the recipient associated to this event

sendingId

Number

The ID of the sending associated to this event

mailingId

Number

The ID of the mailing associated to this event

timestamp

String

The point in time when this event occurred

source

String

An identifier for the source which caused this event

emailAddress

String

The email address of the recipient associated to this event

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/events/unsubscriptions/3' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1019

{
  "id" : 3,
  "type" : "PENDING_UNSUBSCRIPTION_DONE",
  "listId" : 5,
  "recipientId" : 7,
  "sendingId" : 7,
  "mailingId" : 6,
  "timestamp" : "2024-11-19T08:47:23Z",
  "source" : "Your Integration",
  "emailAddress" : "john.doe@example.com",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/events/unsubscriptions/3"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/5"
    },
    "inx:recipient" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/7"
    },
    "inx:mailings" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/6"
    },
    "inx:sendings" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings/7"
    },
    "prev" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/events/unsubscriptions/12"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve unsubscription events collection

GET /events/unsubscriptions{?listIds,startDate,endDate,types,embedded,recipientAttributes}

A GET request on the unsubscription events resource will return the first page of unsubscription events.

Request parameters

Parameter Required Description

listId

no

The ID of the list to retrieve events for

listIds

no

The IDs of the lists to retrieve events for.

startDate

no

The start date (inclusive) for the desired unsubscriptions

endDate

no

The end date (exclusive) for the desired unsubscriptions

types

no

The types for the desired unsubscriptions. Default is all types.

embedded

no

Indicates the relations of the resources that should be embedded in the result.

recipientAttributes

no

Indicates the names of the recipient attributes that should be included in the embedded recipient result. More than one value can be specified with multiple query parameters or comma separated list.

Embeddable relations

Relation Description

inx:recipient

The recipient who was unsubscribed.

Response structure

See section pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/events/unsubscriptions?listIds=5&startDate=2024-11-19T07:47:24Z&endDate=2024-11-19T09:47:24Z&types=PENDING_UNSUBSCRIPTION_DONE,PENDING_UNSUBSCRIPTION&embedded=inx:recipient&recipientAttributes=firstName,lastName' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 3402

{
  "_embedded" : {
    "inx:unsubscription-events" : [ {
      "id" : 1,
      "type" : "PENDING_UNSUBSCRIPTION",
      "listId" : 3,
      "recipientId" : 5,
      "sendingId" : null,
      "mailingId" : 6,
      "timestamp" : "2024-11-19T08:47:24Z",
      "source" : "Your Integration",
      "emailAddress" : "email@example.com",
      "_embedded" : {
        "inx:recipient" : {
          "id" : 7,
          "attributes" : {
            "firstName" : "Emma",
            "lastName" : "Mueller"
          },
          "email" : "email@example.com",
          "lowerEmail" : null,
          "unavailable" : false,
          "last_modified" : "2024-11-19T08:47:24Z",
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/recipients/7?attributes=firstName%2ClastName"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/events/unsubscriptions/1"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        },
        "inx:recipient" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5"
        },
        "inx:mailings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/6"
        }
      }
    }, {
      "id" : 2,
      "type" : "PENDING_UNSUBSCRIPTION_DONE",
      "listId" : 3,
      "recipientId" : 5,
      "sendingId" : 7,
      "mailingId" : 6,
      "timestamp" : "2024-11-19T08:47:24Z",
      "source" : "Unsubscription confirmation",
      "emailAddress" : "email@example.com",
      "_embedded" : {
        "inx:recipient" : {
          "id" : 7,
          "attributes" : {
            "firstName" : "Emma",
            "lastName" : "Mueller"
          },
          "email" : "email@example.com",
          "lowerEmail" : null,
          "unavailable" : false,
          "last_modified" : "2024-11-19T08:47:24Z",
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/recipients/7?attributes=firstName%2ClastName"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/events/unsubscriptions/2"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        },
        "inx:recipient" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5"
        },
        "inx:mailings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/6"
        },
        "inx:sendings" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/sendings/7"
        },
        "prev" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/events/unsubscriptions/1"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/events/unsubscriptions?pageSize=-1&listIds=5&startDate=2024-11-19T07%3A47%3A24Z&endDate=2024-11-19T09%3A47%3A24Z&types=PENDING_UNSUBSCRIPTION_DONE&types=PENDING_UNSUBSCRIPTION&embedded=inx%3Arecipient&recipientAttributes=firstName&recipientAttributes=lastName"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Unsubscribing a recipient from a list

POST /events/unsubscriptions

A POST request with the following payload structure will initiate the unsubscription process for the specified recipient and list. Violations of the constraints will lead to validation errors. Furthermore, the provided listId must correspond to an existing standard mailing list.

The response will contain the resulting event type.

Payload structure

Path Type Description Constraints

listId

Number

The ID of the list the recipient shall be unsubscribed from

  • Must not be null

email

String

The email address of the recipient to unsubscribe

  • Must be a valid email address

  • Must not be null

source

String

An identifier for the source which caused this event

suppliedRemoteAddress

String

The actual supplied IP address of the unsubscription request

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/events/unsubscriptions/' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "listId" : 5,
  "email" : "john.doe@example.com",
  "source" : "Your Integration",
  "suppliedRemoteAddress" : "123.1.1.1"
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 41

{
  "result" : "PENDING_UNSUBSCRIPTION"
}

Target groups

Target groups are objects that contain a set of criteria to filter recipients. Typical criteria include a certain value in a recipient attribute, like the recipient is older than 40 years, or past behavior like the recipient opened the easter mailing. A multitude of criteria can be used to define target groups in Inxmail Professional.

The target group condition

Each target group contains a condition that describes attributes which recipients should meet. The condition is represented by the filterString in a target group. It is also referred to as filter statement.

A filter statement consists of at least one condition that recipients must meet. Multiple conditions may be composed to a filter using the AND/OR operators. There are four possible condition types which may be used:

  • Column condition: Compares the value of a column.

  • Recipient reaction condition: Checks if a recipient opened a mailing or clicked a link.

  • Filter membership condition: Checks if a recipient is a member of a filter.

  • Free expression: Special checks and comparisons.

The following operators may be used to compare columns to a given value or check their content:

  • column = value - checks for equality

  • column <> value - checks for inequality

  • column < value - checks if column value is less than given value

  • column ⇐ value - checks if column value is less than or equal to given value

  • column > value - checks if column value is greater than given value

  • column >= value - checks if column value is greater than or equal to given value

  • column IS_EMPTY - checks if column value is empty

  • column NOT_IS_EMPTY - checks if column value is not empty

The check values have to be specified in the same data type as the column value. The different date types must be specified as follows:

  • Text: "Text" (be sure to escape the double quotes)

  • Datetime: #01.01.1970 13:37:42# (be sure to put a single whitespace between date and time)

  • Date: #01.01.1970#

  • Time: #13:37:42#

  • Integer: 42

  • Floating point: 47.11

  • Boolean: TRUE or FALSE (attention: case sensitive!)

To specify the column which shall be compared it is best to use the Column("columnName") operator.

Using free expressions you can create more powerful statements. The operators which can be used in free expressions are:

  • column LIKE value: checks for equality (case insensitive)

  • column NOT_LIKE value: checks for inequality (case insensitive)

  • column STARTS_WITH value: checks if column value starts with given value

  • column NOT_STARTS_WITH value: checks if column value does not start with given value

  • column ENDS_WITH value: checks if column value ends with given value

  • column NOT_ENDS_WITH value: checks if column value does not end with given value

  • column CONTAINS value: checks if column value contains given value

  • column NOT_CONTAINS value: checks if column value does not contain given value

All of these operators may be used along with text columns. The check values of free expressions may contain wildcards to match a specific pattern. Note: The wildcard character used in free expressions is NOT the asterisk (*) but the percentage sign (%).

Recipient reaction conditions may be used to select recipients who reacted on a specific mailing or link. The operators used for recipient reaction conditions are:

  • HasOpened(mailingId): checks if the recipient opened the specified mailing

  • HasClickedAnyLink(mailingId): checks if the recipient clicked any link in the specified mailing

  • HasClicked(linkId): checks if the recipient clicked the specified link

Filter membership conditions may be used to select recipients who are (or aren’t) a member of another filter. The operators used for these checks are:

  • BelongsToGroup(filterName): checks if the recipient is a member of the specified filter.

  • BelongsNotToGroup(filterName): checks if the recipient is not a member of the specified filter.

Retrieve single target group

GET /target-groups/{id}

A GET request with an ID parameter will return the requested target group.

Request structure

Table 35. /customer/rest/v1/target-groups/{id}
Parameter Description

id

The ID of the target group

Response structure

Path Type Description

id

Number

The ID of the target group

name

String

The name of the target group

description

Null

The description of the target group

listId

Number

The ID of the list holding the target group.

filterString

String

The filter condition of the target group.

creationDate

Null

The timestamp the target-group was last modified.

modificationDate

Null

The timestamp the target-group was created.

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/target-groups/1' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 550

{
  "name" : "examplename",
  "id" : 1,
  "description" : null,
  "listId" : 12,
  "creationDate" : null,
  "modificationDate" : null,
  "filterString" : "myAttribute = \"myAttributeValue\"",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/target-groups/1"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/12"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve target group collection

GET /target-groups{?listId,lastModifiedSince}

A GET request on the target group resource will return the first page of target groups.

Request parameters

Parameter Required Description

listId

no

The ID of the list to retrieve target groups for. If not specified, the target groups of all lists are returned.

lastModifiedSince

no

The date filter for last modified date.

'If-modified-since' HTTP Header

The header makes request conditional

  • if header not set, returns status code 200 and body with existing target-groups. See section Response Structure.

  • if header set and target-groups has not been modified since date, the response is a 304(not modified) without any body.

  • if header set, but target-groups has no modification date at all, the response is a 304(not modified) without any body.

  • if header set and something has changed, returns status code 200 and body with existing target-groups. See section Response Structure.

  • "Wed, 21 Oct 2015 07:28:00 GMT" date format is supported

  • ISO date format is supported (2020-08-25T12:25:34Z)

Request structure

GET /customer/rest/v1/target-groups?listId=15&lastModifiedSince=2023-06-18T10:30:12Z HTTP/1.1
If-modified-since: Wed, 21 Feb 2024 07:28:00 GMT
Host: api.inxmail.com

Response structure

See section pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/target-groups' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 2173

{
  "_embedded" : {
    "inx:target-groups" : [ {
      "name" : "1",
      "id" : 1,
      "description" : null,
      "listId" : 1,
      "creationDate" : null,
      "modificationDate" : null,
      "filterString" : "myAttribute = \"myAttributeValue\"",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/target-groups/1"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/1"
        }
      }
    }, {
      "name" : "2",
      "id" : 2,
      "description" : null,
      "listId" : 1,
      "creationDate" : null,
      "modificationDate" : null,
      "filterString" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/target-groups/2"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/1"
        }
      }
    }, {
      "name" : "3",
      "id" : 3,
      "description" : null,
      "listId" : 2,
      "creationDate" : null,
      "modificationDate" : null,
      "filterString" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/target-groups/3"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/2"
        }
      }
    }, {
      "name" : "4",
      "id" : 4,
      "description" : null,
      "listId" : 3,
      "creationDate" : null,
      "modificationDate" : null,
      "filterString" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/target-groups/4"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/target-groups?afterId=0&pageSize=4"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/target-groups?afterId=4&pageSize=4"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Create a target group

POST /target-groups

A POST request with following payload structure will create a new target group. Violations of the constraints will lead to validation errors.

Payload structure

Path Type Description Constraints

name

String

The name of the new target group

  • Must not be empty

description

String

The description of the new target group

listId

Number

The listId of the new target group. You can use the listId 1 for the system list

  • Must not be null

filterString

String

The filter condition of the target group

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/target-groups/' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "name" : "name",
  "description" : "description",
  "listId" : 5,
  "filterString" : "hasClickedAny(23) AND hasClickedAny(55)"
}'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/target-groups/7
Content-Type: application/hal+json
Content-Length: 259

{
  "id" : 7,
  "listId" : 5,
  "name" : "name",
  "description" : "description",
  "filterString" : "hasClickedAny(23) AND hasClickedAny(55)",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/target-groups/7"
    }
  }
}

Update a target group

PUT /target-groups/7

A PUT request with following payload structure will update an existing target group. Violations of the constraints will lead to validation errors.

Payload structure

Path Type Description Constraints

name

String

The name of the new target group

description

String

The description of the new target group

filterString

String

The filter condition of the target group

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/target-groups/7' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "name",
  "description" : "description",
  "filterString" : "hasClickedAny(23) AND hasClickedAny(55)"
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 349

{
  "name" : "name",
  "id" : 0,
  "description" : "description",
  "listId" : 5,
  "creationDate" : "2024-11-19T08:48:01Z",
  "modificationDate" : "2024-11-19T08:48:01Z",
  "filterString" : "hasClickedAny(23) AND hasClickedAny(55)",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/target-groups/7"
    }
  }
}

Delete existing target group

DELETE /target-groups/{id}

A DELETE request with the following parameter will delete an existing target group:

Table 36. /customer/rest/v1/target-groups/{id}
Parameter Description

id

The ID of the target group to be deleted.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/target-groups/7' -i -X DELETE
Response
HTTP/1.1 204 No Content

Tracking permissions

A tracking permission is the permission of a recipient to allow the Inxmail Professional system to observe and process behaviour like clicking on links or the opening of images in a mailing received by that recipient.

Be aware, that this API only returns the actual permissions (i.e. permissions with state GRANTED), while the Inxmail Professional RPC API returns the tracking permission state of a given recipient on a given list.

Tracking permissions are only considered by the system when the related property is activated.

Retrieve a single tracking permission

GET /tracking-permissions/{id}

A GET request with an ID parameter will return the requested tracking permission.

Request structure

Table 37. /customer/rest/v1/tracking-permissions/{id}
Parameter Description

id

The ID of the tracking permission

Response structure

Path Type Description

id

Number

The ID of the tracking permission

listId

Number

The ID of the list associated to this tracking permission

recipientId

Number

The ID of the recipient associated to this tracking permission

trackingPermissionState

String

The state of this tracking permission

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/tracking-permissions/5' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 560

{
  "id" : 5,
  "listId" : 7,
  "recipientId" : 11,
  "trackingPermissionState" : "GRANTED",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/tracking-permissions/5"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/7"
    },
    "inx:recipient" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/11"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve tracking permission collection

GET /tracking-permissions{?listIds,recipientIds}

or

GET /tracking-permissions{?listIds,emails}

A GET request on the tracking permissions resource will return the first page of tracking permissions.

Please note, that for retrieving a tracking permission it is possible to address the recipient by either the recipient id or the unique email address.

Since the two request parameters 'listIds' and 'recipientIds' (or 'email') are currently mandatory and can only take one id each, the result will contain zero or one objects.

The parameters 'recipientIds' and 'email' must not be used in combination. Exactly one of these parameters must be specified.

Request parameters

Table 38. Request with recipient id
Parameter Required Description

listIds

yes

The ID of the list to retrieve tracking permissions for

recipientIds

yes

The ID of the recipient to retrieve tracking permissions for

or

Table 39. Request with recipient email
Parameter Required Description

listIds

yes

The ID of the list to retrieve tracking permissions for

emails

yes

The email address of the recipient to retrieve tracking permissions for

Response structure

See section pagination.

Example

Request with recipient id
$ curl 'https://api.inxmail.com/customer/rest/v1/tracking-permissions?listIds=7&recipientIds=11' -i -X GET
Request with recipient email
$ curl 'https://api.inxmail.com/customer/rest/v1/tracking-permissions?listIds=7&emails=max.mustermann@example.com' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 845

{
  "_embedded" : {
    "inx:tracking-permissions" : [ {
      "id" : 1,
      "listId" : 7,
      "recipientId" : 11,
      "trackingPermissionState" : "GRANTED",
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/tracking-permissions/1"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/7"
        },
        "inx:recipient" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/11"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/tracking-permissions?pageSize=-1&listIds=7&recipientIds=11"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Create tracking permission

POST /tracking-permissions

A POST request with the following payload structure will create a new tracking permission. Violations of the constraints will lead to validation errors.

The following requirements must be met:

  • The recipient must exist

  • The list must exist

  • The list must be of type STANDARD

  • The recipient must be subscribed to the list, or the list property 'Include Tracking Permission of deleted recipients' must be active

Payload structure

To identify the recipient the recipient id or the email can be used. Using both in one request will lead to a validation error.

Table 40. Payload with recipient id
Path Type Description Constraints

listId

Number

The ID of the list associated to this tracking permission

  • Must not be null

recipientId

Number

The ID of the recipient associated to this tracking permission

trackingPermissionState

String

The state of the tracking permission. Currently only GRANTED state can be posted.

  • Must be GRANTED

  • Must not be null

suppliedRemoteAddress

String

The actual given IP of the request.

  • Must be valid IPv4 address

or

Table 41. Payload with recipient email
Path Type Description Constraints

listId

Number

The ID of the list associated to this tracking permission

  • Must not be null

email

String

The email of the recipient associated to this tracking permission

trackingPermissionState

String

The state of the tracking permission. Currently only GRANTED state can be posted.

  • Must be GRANTED

  • Must not be null

Example

Request with recipient id
$ curl 'https://api.inxmail.com/customer/rest/v1/tracking-permissions/' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "listId" : 21,
  "recipientId" : 22,
  "trackingPermissionState" : "GRANTED",
  "suppliedRemoteAddress" : "168.0.96.4"
}'
Request with recipient email
$ curl 'https://api.inxmail.com/customer/rest/v1/tracking-permissions/' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "listId" : 21,
  "email" : "testine.test@example.de",
  "trackingPermissionState" : "GRANTED"
}'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/tracking-permissions/5
Content-Type: application/hal+json
Content-Length: 216

{
  "id" : 5,
  "listId" : 21,
  "recipientId" : 22,
  "trackingPermissionState" : "GRANTED",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/tracking-permissions/5"
    }
  }
}

In case a tracking permission for a specific list recipient combination already exists, the result will be '200 OK'. This will also produce a tracking permission event.

HTTP/1.1 200 OK
Location: https://api.inxmail.com/customer/rest/v1/tracking-permissions/5
Content-Type: application/hal+json
Content-Length: 216

{
  "id" : 5,
  "listId" : 21,
  "recipientId" : 22,
  "trackingPermissionState" : "GRANTED",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/tracking-permissions/5"
    }
  }
}

Delete tracking permission collection

DELETE /tracking-permissions{?listIds,recipientIds}

or

DELETE /tracking-permissions{?listIds,emails}

A DELETE request will remove a tracking permission. Technically the request will delete a collection of tracking permissions, however because of the required query parameters, effectively only one tracking permission is deleted.

Please note, that for deleting a tracking permission it is possible to address the recipient by either the recipient id or the unique email address.

Deleting an empty collection will also result in 204 No Content. If a list and recipient combination exists then a tracking permission event will be produced regardless whether a permission existed or not.

Example

Request with recipient id
$ curl 'https://api.inxmail.com/customer/rest/v1/tracking-permissions?listIds=7&recipientIds=11' -i -X DELETE
Request with recipient email
$ curl 'https://api.inxmail.com/customer/rest/v1/tracking-permissions?listIds=7&emails=max.mustermann@example.com' -i -X DELETE
Response
HTTP/1.1 204 No Content

Tracking Permission events

Every change to a recipient’s tracking permission on a specific list creates a tracking permission event. A tracking permission event can either be in order to grant a tracking permission or to deny it.

Every tracking permission event has an originator which identifies the person or entity who triggered the event. The originator also represents what action caused the event to occur.

Originators

An originator consists of a set of attributes which identify the person or entity who caused the event. These attributes are:

  • type

  • entity

  • action

  • identity

  • determinedRemoteAddress

  • suppliedRemoteAddress

  • message

The type attribute identifies the originator as defined through a combination of the action and entity attributes.

The entity attribute denotes the type of entity that caused the event. An originator can represent very different entities. For example, an originator can represent an Inxmail Professional user, an integration using this API or the Inxmail Professional application itself.

Each of these entities can perform various actions that cause a tracking permission to be granted or revoked. For example, an Inxmail Professional user can import tracking permissions, change them manually or unsubscribe the recipient which in turn revokes the tracking permission. The type of this action is conveyed using the action attribute.

To identify the person or entity who caused the event, the combination of the identity, determinedRemoteAddress and suppliedRemoteAddress attributes can be used.

The identity attribute contains information which can be used to identify the person or entity that caused the event, if available. What this information is depends on the type of the entity. It could, for example, be the ID of an Inxmail Professional user, the name of an integration or the ID of a recipient. See the list of entity types for instructions on how to interpret the identity attribute.

The determinedRemoteAddress attribute contains the remote address of the entity that caused the event, as determined by the Inxmail Professional application, if available.

The suppliedRemoteAddress attribute contains the remote address of the entity that caused the event, as provided by a third party, if available. In some cases, Inxmail Professional cannot determine the remote address of the person or entity trying to make a change, because another system (e.g. an integration which provides a subscription form) acts as a proxy of that entity. In these cases the proxy system may supply the correct remote address of the entity on whose behalf it is making the change. This address will be stored in the suppliedRemoteAddress attribute. Keep in mind this is an optional free text field and may contain values other than an IP address.

The message attribute may contain a message provided by the entity that caused the event.

Originator types

The following table describes the available types of originator along with the action & entity combination that defines it.

Originator type Originator entity Originator action

ACTION

ACTION

ACTION

FORCED_SUBSCRIPTION

USER

FORCED_SUBSCRIPTION

API_IMPORT

REST_API

RECIPIENT_IMPORT

MANUAL_IMPORT

USER

RECIPIENT_IMPORT

AUTOMATED_IMPORT

IMPORT_AUTOMATION

RECIPIENT_IMPORT

REMOVED_FROM_LIST

SYSTEM

RECIPIENT_REMOVED_FROM_LIST

RPC_API

RPC_API

RECIPIENT_MANIPULATION

CLICK

RECIPIENT

CLICK

EMAIL_SUNSCRIPTION

RECIPIENT

EMAIL_SUBSCRIPTION

EMAIL_UNSUBSCRIPTION

RECIPIENT

EMAIL_UNSUBSCRIPTION

FORCED_UNSUBSCRIPTION

USER

FORCED_UNSUBSCRIPTION

SUBSCRIPTION_SERVLET

SUBSCRIPTION_SERVLET

SUBSCRIPTION_OR_UNSUBSCRIPTION

SYNC_AGENT

SYNC_SOURCE

SYNC

REST_API

REST_API

SUBSCRIPTION_OR_UNSUBSCRIPTION

USER_UNSUBSCRIPTION

USER

MANUAL_UNSUBSCRIPTION

REMOVED_FROM_SYSTEM

SYSTEM

RECIPIENT_REMOVED_FROM_SYSTEM

LIST_REMOVED

SYSTEM

LIST_REMOVED

TRACKING_PERMISSION_LINK

RECIPIENT

TRACKING_PERMISSION_CLICK

USER_MANUAL_CHANGE

USER

MANUAL_CHANGE

RPC_API_SUBSCRIPTION

RPC_API

SUBSCRIPTION_OR_UNSUBSCRIPTION

RPC_API_TRACKING_PERMISSION_MANAGER

RPC_API

MANUAL_CHANGE

UNKNOWN

UNKNOWN

UNKNOWN

REMOVED_ORPHANED

SYSTEM

REMOVED_ORPHANED

SUBSCRIPTION_JSP

JSP

JSP_SUBSCRIPTION

Originator entities

The following table describes the available types of originator entities and how to interpret the identity attribute for that type of entity.

Originator entity Description Identity

RECIPIENT

A recipient.

No identity unless the action is TRACKING_PERMISSION_CLICK in which case the identity is the ID of the link, otherwise use the remote address.

USER

An Inxmail Professional user.

The ID of the Inxmail Professional user.

REST_API

A request initiated using this API.

The name of the integration using this API.

RPC_API

A request initiated using the SOAP based Inxmail Professional API.

The ID of the API user.

IMPORT_AUTOMATION

The import automation which performs automatic scheduled recipient imports.

The ID of the specific import automation.

ACTION

An action which affects tracking permissions either directly or indirectly.

The ID of the action.

SUBSCRIPTION_SERVLET

A request initiated using the subscription servlet.

No identity, use the remote address.

SYNC_SOURCE

A sync source which is a remote service used to synchronize recipients between Inxmail Professional and a database.

The name of the sync source.

SYSTEM

The Inxmail Professional application itself.

No identity.

JSP

A request initiated using the JSP.

No identity.

UNKNOWN

The entity that caused the event is unknown.

No identity.

Originator actions

The following table describes the available types of originator actions.

Originator action Description

TRACKING_PERMISSION_CLICK

A click on a tracking permission link caused the tracking permission to change.

CLICK

A click on a link, most notably an unsubscription or subscription verification link, which caused the tracking permission to change.

MANUAL_CHANGE

The tracking permission was changed manually (i.e. by a user).

SUBSCRIPTION_OR_UNSUBSCRIPTION

A recipient was either subscribed or unsubscribed, changing the tracking permission.

EMAIL_SUBSCRIPTION

A subscription was performed by sending a specially crafted email, thus changing the tracking permission.

EMAIL_UNSUBSCRIPTION

An unsubscription was performed by sending a specially crafted email, thus changing the tracking permission.

MANUAL_UNSUBSCRIPTION

A recipient was unsubscribed manually (i.e. by a user), thus revoking the tracking permission.

FORCED_SUBSCRIPTION

An incomplete subscription process was completed manually (i.e by a user).

FORCED_UNSUBSCRIPTION

An incomplete unsubscription process was completed manually (i.e by a user).

RECIPIENT_IMPORT

A recipient import was used to import tracking permissions.

SYNC

A recipient sync using the sync agent caused the tracking permission to change.

RECIPIENT_MANIPULATION

A recipient was manipulated through an integration, changing the tracking permission.

ACTION

An action affecting tracking permissions either directly or indirectly was triggered.

RECIPIENT_REMOVED_FROM_LIST

A recipient was removed from a list, thus removing (i.e. revoking) the associated tracking permission.

RECIPIENT_REMOVED_FROM_SYSTEM

A recipient was removed from the system, thus removing (i.e. revoking) the tracking permission.

LIST_REMOVED

A list was removed, thus removing (i.e. revoking) the tracking permission of all recipients who were subscribed to that list.

REMOVED_ORPHANED

If configured accordingly, removing a recipient from a list does not revoke that recipients tracking permission. If this setting is reverted, the tracking permissions of recipients who are no longer subscribed to the affected list (i.e. orphaned) will be removed.

JSP_SUBSCRIPTION

A subscription was performed by using a JSP, thus changing the tracking permission.

UNKNOWN

The action that caused the event is unknown.

Retrieving a tracking permission event

GET /events/tracking-permissions/{id}

A GET request with an ID parameter will return the requested event.

Request structure

Table 42. /customer/rest/v1/events/tracking-permissions/{id}
Parameter Description

id

The ID of the event

Response structure

Path Type Description

id

Number

The ID of the event

listId

Number

The ID of the list associated to this event

recipientId

Number

The ID of the recipient associated to this event

newTrackingPermissionState

String

The new tracking permission state resulting from this event

timestamp

String

The point in time when this event occurred

originator

Object

The originator that caused this event

originator.type

String

The originator type that caused this event

originator.entity

String

The type of entity that caused this event

originator.action

String

The type of action that caused this event

originator.identity

String

The identity of the entity that caused this event

originator.determinedRemoteAddress

String

The remote address of the entity that caused this event, as determined by the Inxmail Professional application

originator.suppliedRemoteAddress

String

The remote address of the entity that caused this event, as supplied by a third party

originator.message

String

A message provided by the entity that caused this event

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/events/tracking-permissions/5' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 878

{
  "id" : 5,
  "timestamp" : "2024-11-19T08:47:24Z",
  "listId" : 7,
  "recipientId" : 11,
  "originator" : {
    "type" : "RPC_API",
    "entity" : "RPC_API",
    "action" : "SUBSCRIPTION_OR_UNSUBSCRIPTION",
    "determinedRemoteAddress" : "127.0.0.1",
    "suppliedRemoteAddress" : "1.2.3.4",
    "message" : "subscription form",
    "identity" : "23"
  },
  "newTrackingPermissionState" : "GRANTED",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/events/tracking-permissions/5"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/7"
    },
    "inx:recipient" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/11"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve tracking permission event collection

GET /events/tracking-permissions{?listIds,recipientIds,startDate,endDate,embedded,recipientAttributes,eventOriginatorTypes}

or

GET /events/tracking-permissions{?listIds,emails,startDate,endDate,embedded,recipientAttributes,eventOriginatorTypes}

A GET request on the tracking permission events resource will return the first page of tracking permission events.

Please note: The request parameters to filter recipients is in plural. However, only one recipient can be filtered per request at the moment. This naming scheme is a measure to future-proof the API. If there is demand to filter multiple recipients per request we will add that feature in the future without changing the name of the parameter, hence keeping compatibility.

Please also keep in mind, that for retrieving a tracking permission event it is possible to address the recipient by either the recipient id or the recipient email address. The parameters 'recipientIds' and 'emails' must not be used in combination. Using both in one request will lead to a validation error.

Request parameters

Parameter Required Description

listIds

no

The IDs of the lists to retrieve events for

recipientIds

no

The ID of the recipient to retrieve events for

emails

no

The email address of the recipient to retrieve events for

startDate

no

The start date (inclusive) for the desired tracking permission events

endDate

no

The end date (exclusive) for the desired tracking permission events

embedded

no

Indicates the relations of the resources that should be embedded in the result.

recipientAttributes

no

Indicates the names of the recipient attributes that should be included in the embedded recipient result. More than one value can be specified with multiple query parameters or comma separated list.

eventOriginatorTypes

no

details of the originator that triggered this event

Embeddable relations

Relation Description

inx:recipient

The recipient whose tracking permission was altered.

Response structure

See section pagination.

Example

Request with recipient id
$ curl 'https://api.inxmail.com/customer/rest/v1/events/tracking-permissions?listIds=7,8&recipientIds=11&startDate=2024-11-19T07:47:26Z&endDate=2024-11-19T09:47:26Z&embedded=inx:recipient&recipientAttributes=firstName,lastName&eventOriginatorTypes=RPC_API,USER_UNSUBSCRIPTION' -i -X GET
Request with recipient email
$ curl 'https://api.inxmail.com/customer/rest/v1/events/tracking-permissions?listIds=7,8&emails=email@example.com&startDate=2024-11-19T07:47:26Z&endDate=2024-11-19T09:47:26Z&embedded=inx:recipient&recipientAttributes=firstName,lastName&eventOriginatorTypes=RPC_API,USER_UNSUBSCRIPTION' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 3361

{
  "_embedded" : {
    "inx:tracking-permission-events" : [ {
      "id" : 1,
      "timestamp" : "2024-11-19T08:47:26Z",
      "listId" : 7,
      "recipientId" : 11,
      "originator" : {
        "type" : "RPC_API",
        "entity" : "RPC_API",
        "action" : "RECIPIENT_MANIPULATION",
        "determinedRemoteAddress" : "0.0.0.0",
        "suppliedRemoteAddress" : "0.0.0.0",
        "message" : "some message",
        "identity" : "some identity"
      },
      "newTrackingPermissionState" : "GRANTED",
      "_embedded" : {
        "inx:recipient" : {
          "id" : 11,
          "attributes" : {
            "firstName" : "Emma",
            "lastName" : "Mueller"
          },
          "email" : "email@example.com",
          "lowerEmail" : null,
          "unavailable" : false,
          "last_modified" : "2024-11-19T08:47:26Z",
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/recipients/11?attributes=firstName%2ClastName"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/events/tracking-permissions/1"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/7"
        },
        "inx:recipient" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/11"
        }
      }
    }, {
      "id" : 2,
      "timestamp" : "2024-11-19T08:47:26Z",
      "listId" : 7,
      "recipientId" : 11,
      "originator" : {
        "type" : "USER_UNSUBSCRIPTION",
        "entity" : "USER",
        "action" : "MANUAL_UNSUBSCRIPTION",
        "determinedRemoteAddress" : "0.0.0.0",
        "suppliedRemoteAddress" : "0.0.0.0",
        "message" : "some message",
        "identity" : "some identity"
      },
      "newTrackingPermissionState" : "DENIED",
      "_embedded" : {
        "inx:recipient" : {
          "id" : 11,
          "attributes" : {
            "firstName" : "Emma",
            "lastName" : "Mueller"
          },
          "email" : "email@example.com",
          "lowerEmail" : null,
          "unavailable" : false,
          "last_modified" : "2024-11-19T08:47:26Z",
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/recipients/11?attributes=firstName%2ClastName"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/events/tracking-permissions/2"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/7"
        },
        "inx:recipient" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/11"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/events/tracking-permissions?pageSize=-1&listIds=7&listIds=8&recipientIds=11&startDate=2024-11-19T07%3A47%3A26Z&endDate=2024-11-19T09%3A47%3A26Z&embedded=inx%3Arecipient&recipientAttributes=firstName&recipientAttributes=lastName&eventOriginatorTypes=RPC_API&eventOriginatorTypes=USER_UNSUBSCRIPTION"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Recipient Import

The most efficient and safe way to sync recipients into Inxmail Professional is to use the CSV import capabilities. To use this feature, you have to construct a CSV document which can then be uploaded directly to the Inxmail Professional server. There is no need for an intermediary file server in this scenario.

Please note, that to ensure a consistent state of recipient data, all recipient imports are performed sequentially, in order of arrival. This includes recipient imports performed by other REST API calls, as well as those performed by the import automation feature or imports triggered manually by a user of the Inxmail Professional Client.

Also note, that the import is performed asynchronously. The result of an import request is a status monitor which can be used to check the status of the import, as well as some progress information regarding the number of lines imported thus far and the number of lines which could not be imported to date.

The maximum size of a CSV file to be imported is 128 MB by default, but can be configured. Exceeding the maximum upload size leads to a response with the error code 413, which means that the payload is too large to handle.

Import multiple recipients by uploading a CSV file

POST /imports/recipients{?listId,resubscribe,truncate,importConflictMode,trackingPermissionConflictMode}

A POST request with a, potentially compressed, CSV file multipart will trigger a recipient import which uses the CSV file as source.

Request structure

To upload the CSV file the request has to be a multipart request (e.g. multipart/form-data) with a request part called file. This request part must contain either a proper CSV file or a gzip compressed version of a proper CSV file. In the latter case, the Content-Disposition header must include the filename attribute which must end in .csv.gz. For example: Content-Disposition: form-data; name="file"; filename="import.csv.gz". See the curl examples for reference.

Required CSV file structure

In order for a CSV file to be imported successfully, it must adhere to a certain structure. First of all, the file encoding must be UTF-8.

The first line of the CSV file must contain the names of the attributes to import. There must be a column containing the email address and its name must be email. The name of the optional column containing the tracking permission must be trackingPermission. All other columns must match the name of the corresponding recipient attribute in Inxmail Professional. There must not be an empty column name and no two or more columns are allowed to share the same name.

The column separator has to be a semicolon (;) and the text delimiter a double quote ("). If you wish to use a double quote inside the value for a text attribute, you have to escape it with a backslash (e.g. "text with \"quotes\" inside").

Dates and times have to be provided in ISO-8601 format and UTC+0 (see also Date/Time format and time zone). The following patterns are in use for the different date/time types:

Date/Time type Pattern

Date with time

YYYY-MM-DD’T’HH:MM:SSZ

Date only

YYYY-MM-DD

Time only

HH:MM:SSZ

For numbers, if you wish to include a thousands separator, use a comma (,). For floating point numbers, use a dot (.) as decimal separator.

For booleans, the text value true will evaluate to the boolean value true. Any other text, including empty value, will evaluate to the boolean value false.

An empty CSV token (;;), the empty string (;"";) and a string consisting of one or more whitespaces (;" ";) will be interpreted as an empty value.

Query parameters

When no further query parameters are present, the default behaviour is to import the recipients into the system but don’t subscribe them to any list which they are not already a member of.

Please note, that recipients in Inxmail Professional are stored uniquely and not per list. This means that an import into the system does change the affected recipient attributes of any existing recipient in all lists they are members of (either subscribed or unsubscribed).

To manipulate the behaviour of the import, you can use the following query parameters:

Parameter Required Description

listId

no

The ID of the target list to import the recipients into, by subscribing them to the list. The target list must be a list of type STANDARD. If this parameter is omitted, the recipients will only be imported into the system and not subscribed to any list.

resubscribe

no

If true any recipient in the CSV file who was previously unsubscribed from the target list will be re-subscribed. This parameter only takes effect if the listId parameter is in use. The default is false.

truncate

no

If true all subscribed members of the target list will be removed from the list prior to the import. Use with caution. This parameter only takes effect if the listId parameter is in use. The default is false.

importConflictMode

no

Possible values are KEEP_EXISTING,OVERWRITE_EXCEPT_EMPTY,OVERWRITE_FULL and UPDATE. The default value is OVERWRITE_FULL. For more information see here

trackingPermissionConflictMode

no

Possible values are KEEP_EXISTING,OVERWRITE_EXCEPT_EMPTY and OVERWRITE_FULL. The default value is OVERWRITE_FULL. For more information see here

An import affects both recipient attributes and tracking permissions. The default value of importConflictMode is OVERWRITE_FULL, but can be modified by specifying one of the following import conflict modes:

Import Conflict Mode Description

KEEP_EXISTING

No recipient attributes of an existing recipient will be changed by the import.

OVERWRITE_EXCEPT_EMPTY

Every recipient attribute will be overwritten with the corresponding value in the CSV file, assuming the value in the CSV file is not empty.

OVERWRITE_FULL

Every recipient attribute will be overwritten with the corresponding value in the CSV file, even if the value in the CSV file is empty. Keep in mind that an empty value in the CSV file will lead to the deletion of an existing recipient attribute value. Empty boolean values in the CSV file will be interpreted as false.

UPDATE

No existing existing recipient attributes will be overwritten. If the value of a recipient attribute is empty, but is not empty in the CSV file, it will add the value to the recipient attribute.

The default value of trackingPermissionConflictMode is OVERWRITE_FULL, but can be modified by specifying one of the following tracking permission conflict modes:

Tracking Permission Conflict Mode Description

KEEP_EXISTING

No tracking permissions of an existing recipient will be changed by the import.

OVERWRITE_EXCEPT_EMPTY

Every tracking permission will be overwritten with the corresponding value in the CSV file, assuming the value in the CSV file is not empty. The value GRANTED (case insensitive matching) sets the permission to track this recipient. All other values than GRANTED will be interpreted as no permission to track this recipient.

OVERWRITE_FULL

Every tracking permission will be overwritten with the corresponding value in the CSV file, even if the value in the CSV file is empty. The value GRANTED (case insensitive matching) sets the permission to track this recipient. All other values than GRANTED will be interpreted as no permission to track this recipient. An empty value will revoke the tracking permission.

Response structure

The response to an import request is the content of a newly generated status monitor for that import. As the import is performed asynchronously, you can use this status monitor to check the current status of the import.

For a description of the structure of the status monitor, see section Response Structure of chapter Observe the status of a recipient import.

Example

Request when uploading an uncompressed CSV file
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/' -i -X POST \
    -H 'Content-Type: multipart/form-data' \
    -F 'file=@import.csv;type=text/csv'
Request when uploading a gzip compressed CSV file
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/' -i -X POST \
    -H 'Content-Type: multipart/form-data' \
    -F 'file=@import.csv.gz;type=application/gzip'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/imports/recipients/5
Content-Type: application/hal+json
Content-Length: 574

{
  "id" : 5,
  "successCount" : 38,
  "failCount" : 42,
  "state" : "PROCESSING",
  "triggerType" : null,
  "beginDate" : null,
  "endDate" : null,
  "files" : null,
  "targetListId" : null,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/5"
    },
    "inx:files" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/5/files"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Observe the status of a recipient import

GET /imports/recipients/{importId}

A GET request with an ID parameter will return the requested recipient import.

Request structure

The following path parameters are required:

Table 43. /customer/rest/v1/imports/recipients/{importId}
Parameter Description

importId

The Id of of the recipient import

Response structure

Path Type Description

id

Number

The ID of the recipient import

state

String

The state of the import. Possible values are: NEW, PROCESSING, SUCCESS, FAILED, CANCELED

triggerType

Null

The trigger type state of the import. Possible values are:

successCount

Number

The number of successfully imported records so far

failCount

Number

The current number of records which could not be imported

beginDate

Null

The begin date of the import

endDate

Null

The end date of the import

files

Null

The files of the import

targetListId

Null

The target list id of the import

_links

Object

Links to other resources

The values for the state field have the following meaning:

State Description

NEW

The import has been acknowledged but has not yet started processing.

PROCESSING

The import is in progress.

SUCCESS

The import has finished successfully. This does not imply that all records were successfully imported, though.

FAILED

The import could not be performed. This can either be due to a general problem or implies that no record at all could be imported.

CANCELED

The import was aborted by a user.

There are the following link relations in the _links field:

Relation Description

self

Link to this recipient import

inx:files

Link to files of this recipient import

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/5' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 574

{
  "id" : 5,
  "successCount" : 38,
  "failCount" : 42,
  "state" : "PROCESSING",
  "triggerType" : null,
  "beginDate" : null,
  "endDate" : null,
  "files" : null,
  "targetListId" : null,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/5"
    },
    "inx:files" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/5/files"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Observe the status of a file import

GET /imports/recipients/{importId}/files/{fileId}

A GET request with an import ID parameter and a file ID parameter will return the requested file import.

Request structure

The following path parameters are required:

Table 44. /customer/rest/v1/imports/recipients/{importId}/files/{fileId}
Parameter Description

importId

The Id of the recipient import

fileId

The Id of the file

Response structure

Path Type Description

name

String

The name of the file

state

String

The state of the import. Possible values are: NEW, PREFETCHING, READY_TO_PROCESS, PREFETCH_FAILED, PROCESSING, SUCCESSFUL, FAILED, DEQUEUED, CANCELED

currentCount

Number

The number of imported records so far

successCount

Number

The number of successfully imported records so far

failedCount

Number

The current number of records which could not be imported

id

Number

The ID of the file import

_links

Object

Links to other resources

The values for the state field have the following meaning:

State Description

NEW

The file import has been acknowledged but has not yet started processing.

PREFETCHING

File is being retrieved. Only relevant for Import Automation imports.

READY_TO_PROCESS

Ready for processing. Maybe waiting for another import to finish.

PREFETCH_FAILED

Failed to load the file. Only relevant for Import Automation imports.

PROCESSING

The file import is in progress.

SUCCESSFUL

The file import has finished successfully.

FAILED

The file import could not be performed.

DEQUEUED

The file has been removed from the queue and will not be imported.

CANCELED

The file import was aborted by a user.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/5/files/123' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 542

{
  "name" : "filename.csv",
  "state" : "SUCCESSFUL",
  "currentCount" : 101,
  "successCount" : 100,
  "failedCount" : 1,
  "id" : 123,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/5/files/123"
    },
    "inx:errors" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/5/files/123/errors"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve import execution history collection

GET /imports/recipients

A GET request with will return the first page of import execution history.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1105

{
  "_embedded" : {
    "inx:execution" : [ {
      "state" : "SUCCESS",
      "id" : 201,
      "triggerType" : "MANUAL",
      "failCount" : 0,
      "successCount" : 1,
      "beginDate" : "2024-11-19T08:47:07Z",
      "endDate" : "2024-11-19T08:47:07Z",
      "targetListId" : 3,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/201"
        }
      }
    }, {
      "state" : "SUCCESS",
      "id" : 201,
      "triggerType" : "MANUAL",
      "failCount" : 0,
      "successCount" : 1,
      "beginDate" : "2024-11-19T08:47:07Z",
      "endDate" : "2024-11-19T08:47:07Z",
      "targetListId" : 3,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/201"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients?pageSize=1"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve import files collection

GET /imports/recipients/{importId}/files

A GET request with an import ID on the files resource will return the first page of import files.

Request structure

The following path parameters are required:

Table 45. /customer/rest/v1/imports/recipients/{importId}/files
Parameter Description

importId

The Id of the recipient import

Response structure

See section pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/1/files' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1084

{
  "_embedded" : {
    "inx:files" : [ {
      "name" : "file.csv",
      "id" : 1,
      "state" : "SUCCESSFUL",
      "successCount" : 5,
      "currentCount" : 7,
      "failedCount" : 1,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/1/files/1"
        }
      }
    }, {
      "name" : "other.csv",
      "id" : 5,
      "state" : "FAILED",
      "successCount" : 32,
      "currentCount" : 112,
      "failedCount" : 99,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/1/files/5"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/1/files?afterId=0&pageSize=2"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/1/files?afterId=5&pageSize=2"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve import errors collection

GET /imports/recipients/{importId}/files/{importFileId}/errors

A GET request with an import ID and an import file ID on the errors resource will return the first page of import errors.

Request structure

The following path parameters are required:

Table 46. /customer/rest/v1/imports/recipients/{importId}/files/{importFileId}/errors
Parameter Description

importId

The Id of the recipient import

importFileId

The Id of the import file

Response structure

See section pagination.

The resources will have following response structure:

Path Type Description

email

String

Optional: e-mail address of line

line

Number

Optional: number of affected line

column

Number

Optional: number of affected column

error

String

The code of the error. Possible values are: COLUMN_NOT_FOUND_WARN, IGNORED_TRACKING_PERMISSION_WARN, SAVE_ERROR, UNSUBSCRIPTION_ERROR, BLACKLIST_ERROR, IGNORED_IMPORT_ERROR, IMPORT_CRASHED_ERROR, DELETE_RECIPIENTS_ERROR, LINE_PARSE_ERROR, ATTRIBUTE_PARSE_ERROR, EMAIL_PARSE_ERROR, HEADER_ERROR

For specific errors, the response structure consists of an additional field of type String called value. Its meaning differentiates between these error types:

Error Description of value

COLUMN_NOT_FOUND_WARN

The name of the column in the CSV file which could not be matched.

IGNORED_TRACKING_PERMISSION_WARN

The name of the tracking permission column.

DELETE_RECIPIENTS_ERROR

The list id from the list the recipient could not be deleted from.

ATTRIBUTE_PARSE_ERROR

The value of the attribute which could not be parsed.

EMAIL_PARSE_ERROR

The value of the email which could not be parsed.

The values for the error field have the following meaning:

Error Description Resolution

COLUMN_NOT_FOUND_WARN

Column not found.

Check for missing columns.

IGNORED_TRACKING_PERMISSION_WARN

Tracking permission column ignored. Tracking permission import in system list is not possible.

Set listId parameter to import into specific list.

SAVE_ERROR

Recipient data could not be written.

If you encounter this error, please contact us.

UNSUBSCRIPTION_ERROR

Email is unsubscribed and automatic re-subscription is disabled. This prevents recipients who unsubscribed from the target list to be contacted again without permission.

Either exclude the recipient from the next import or explictly enable re-subscription.

BLACKLIST_ERROR

Email address is on blacklist.

Either exclude the recipient from the next import or remove the address email in line line from the blacklist.

IGNORED_IMPORT_ERROR

Ignore unknown setting is active and recipient was not in list.

Either exclude the recipient from the next import or disable the ignore unknown setting.

IMPORT_CRASHED_ERROR

An unexpected error occured while importing.

Check line with number line.

DELETE_RECIPIENTS_ERROR

Error deleting recipients.

If you encounter this error, please contact us.

LINE_PARSE_ERROR

Line could not be parsed.

Check if line line contains valid CSV data in compliance with section Required CSV file structure.

ATTRIBUTE_PARSE_ERROR

Attribute could not be parsed.

Check value in line line and column column for compliance with section Required CSV file structure.

EMAIL_PARSE_ERROR

Email address could not be parsed.

Check whether the value in line line and column column is a valid email address.

HEADER_ERROR

Header error

Check if the header contains valid CSV data in compliance with section Required CSV file structure.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/1/files/1/errors' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 790

{
  "_embedded" : {
    "inx:errors" : [ {
      "value" : "Attribute1xyz",
      "error" : "EMAIL_PARSE_ERROR",
      "line" : 5,
      "column" : 1
    }, {
      "value" : "Attribute1xyz",
      "error" : "COLUMN_NOT_FOUND_WARN"
    }, {
      "error" : "BLACKLIST_ERROR",
      "email" : "john.doe@example.com",
      "line" : 42
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/1/files/1/errors?afterId=0&pageSize=3"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/1/files/1/errors?afterId=5&pageSize=3"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Preview of imported recipients by uploading a CSV file

GET /imports/recipients/store/{id}/sourcepreview

A GET request with id of imported file as a parameter. Provides output of the first 20 lines.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/store/2/sourcepreview' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1078

{
  "lines" : [ "'email','AttributeValue'", "'recipient0@example.com','attributeValue0'", "'recipient1@example.com','attributeValue1'", "'recipient2@example.com','attributeValue2'", "'recipient3@example.com','attributeValue3'", "'recipient4@example.com','attributeValue4'", "'recipient5@example.com','attributeValue5'", "'recipient6@example.com','attributeValue6'", "'recipient7@example.com','attributeValue7'", "'recipient8@example.com','attributeValue8'", "'recipient9@example.com','attributeValue9'", "'recipient10@example.com','attributeValue10'", "'recipient11@example.com','attributeValue11'", "'recipient12@example.com','attributeValue12'", "'recipient13@example.com','attributeValue13'", "'recipient14@example.com','attributeValue14'", "'recipient15@example.com','attributeValue15'", "'recipient16@example.com','attributeValue16'", "'recipient17@example.com','attributeValue17'", "'recipient18@example.com','attributeValue18'" ],
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/store/2/sourcepreview"
    }
  }
}

Advanced Recipient Import

For general information about importing a csv file to Inxmail Professional see Recipient Import. With the Advanced Recipient Import you have the ability to create a configuration that specifies how the imported file should be read, such as the column separator. Once the configuration is set, you can manually start the import process.

Please note that all uploaded Files that have been sent to Inxmail Professional will be deleted once per day, if they are older than 4 hours, or if the import was started.

Post an import file

POST /imports/recipients/store

A POST request will store the attached file to Inxmail Professional and makes it available to use it for later imports. To upload the file the request has to be a multipart request (e.g. multipart/form-data) with a request part called file. This request part must contain either a proper csv file, a xlsx file or a gzip compressed version of either a csv file or a xlsx file. In the latter case, the Content-Disposition header must include the filename attribute which must end in .csv.gz or .xlsx.gz. For example: Content-Disposition: form-data; name="file"; filename="import.csv.gz". See the curl examples for reference.

Required CSV file structure

The maximum size of a file to be imported is 128 MB by default, but can be configured. Exceeding the maximum upload size leads to a response with the error code 400. The validity of the uploaded file is determined in the second step based on a predefined configuration, the validation will happen if you request a Preview of the import, or start the actual Import

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/store' -i -X POST \
    -H 'Content-Type: multipart/form-data' \
    -F 'file=@import.csv;type=text/csv'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/imports/recipients/store
Content-Type: application/hal+json
Content-Length: 196

{
  "id" : 2,
  "originalFileName" : "import.csv",
  "lineCount" : 200,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/store"
    }
  }
}
Table 47. Response Structure
Path Type Description

id

Number

The id of the file, stored to the server

originalFileName

String

The name of the file, stored to the server

lineCount

Number

Number of lines which are in the imported file

_links

Object

Links to other resources

Delete an import file

DELETE /imports/recipients/store/{id}

A DELETE request on an import file, will delete the requested files.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/store/2' -i -X DELETE
Response
HTTP/1.1 204 No Content

Retrieve a single configuration

GET /imports/recipients/configuration-template/{id}

A GET request will return the requested configuration template with the given id

Response structure
{
  "decimalSeparator" : ",",
  "encoding" : "UTF-8",
  "dateFormat" : "dd.MM.yyyy",
  "booleanMatchValue" : true,
  "dateTimeFormat" : "dd.MM.yyyy HH:mm:ss",
  "timeFormat" : "HH:mm:ss",
  "thousandsSeparator" : ".",
  "booleanParserPattern" : "Yes",
  "timezone" : "UTC",
  "columnSeparator" : ",",
  "textDelimiter" : "'",
  "textDelimiterEscaping" : "DOUBLE",
  "id" : 0,
  "trackingPermissionConflictMode" : "KEEP_EXISTING",
  "importConflictMode" : "SKIP",
  "trackingPermissionGrantedValue" : "true",
  "clearListBeforeImport" : true,
  "unsubscribeSubscribedRecipients" : true,
  "ignoreUnknownRecipients" : true,
  "targetList" : 1,
  "targetListTab" : "NONE",
  "targetFiletype" : "CSV",
  "notifyOnSuccess" : true,
  "emailAddressColumn" : "EmailAddressColumnValue",
  "trackingPermissionColumnName" : "TrackingPermissionColumnName",
  "notifyOnFailure" : true,
  "notifyOnCancel" : true,
  "notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
  "resubscribeUnsubscribedRecipients" : true,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/12"
    }
  }
}

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/12' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1165

{
  "decimalSeparator" : ",",
  "encoding" : "UTF-8",
  "dateFormat" : "dd.MM.yyyy",
  "booleanMatchValue" : true,
  "dateTimeFormat" : "dd.MM.yyyy HH:mm:ss",
  "timeFormat" : "HH:mm:ss",
  "thousandsSeparator" : ".",
  "booleanParserPattern" : "Yes",
  "timezone" : "UTC",
  "columnSeparator" : ",",
  "textDelimiter" : "'",
  "textDelimiterEscaping" : "DOUBLE",
  "id" : 0,
  "trackingPermissionConflictMode" : "KEEP_EXISTING",
  "importConflictMode" : "SKIP",
  "trackingPermissionGrantedValue" : "true",
  "clearListBeforeImport" : true,
  "unsubscribeSubscribedRecipients" : true,
  "ignoreUnknownRecipients" : true,
  "targetList" : 1,
  "targetListTab" : "NONE",
  "targetFiletype" : "CSV",
  "notifyOnSuccess" : true,
  "emailAddressColumn" : "EmailAddressColumnValue",
  "trackingPermissionColumnName" : "TrackingPermissionColumnName",
  "notifyOnFailure" : true,
  "notifyOnCancel" : true,
  "notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
  "resubscribeUnsubscribedRecipients" : true,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/12"
    }
  }
}

Creating a new Configuration

POST /imports/recipients/configuration-template

A POST request with the payload structure as described following payload will crate a new configuration with the specified values. Violations of the constraints will lead to validation errors.

Payload structure

Path Type Description Constraints

emailAddressColumn

String

The name of the column in the csv file that contains the recipient’s email address.

  • Must match the regular expression [a-zA-Z0-9_-]+

  • Must not be null

trackingPermissionColumnName

String

The name of the column in the csv file that contains the information about the tracking permissions.

  • Must not be null

notifyOnSuccess

Boolean

If an email should be sent upon a successful import, to the addresses defined in notifyRecipients.

notifyOnFailure

Boolean

If an email should be sent upon a failed import, to the addresses defined in notifyRecipients.

notifyOnCancel

Boolean

If an email should be sent upon a canceled import, to the addresses defined in notifyRecipients.

notifyRecipients

Array

The list of email addresses that should be notified on success, failure, or cancellation of an import, if enabled.

  • Must not be null

columnSeparator

String

The character which is used to separate the columns.

textDelimiter

String

The character used to separate text fields.

textDelimiterEscaping

String

The character used to escape the text delimeter

dateTimeFormat

String

The date-time format used to parse the date-time columns

dateFormat

String

The date format used to parse the date columns

timeFormat

String

The time format used to parse the time columns

thousandsSeparator

String

The character which is used to to group digits in large numbers for better readability.

  • Must be one of ., ,, _, , '

decimalSeparator

String

The character which is used to separate the integer part from the fractional part of a number.

encoding

String

The encoding of the import file.

booleanParserPattern

String

The pattern which is used to parse text to boolean values.

booleanMatchValue

Boolean

In which boolean value texts should be parsed that match the booleanParsePattern.

trackingPermissionGrantedValue

String

The pattern which indicates that a recipient has tracking permissions.

  • Must not be null

timezone

String

The Time Zone for the Date Time values

importConflictMode

String

The strategy to handle import conflicts. For more information see here

  • Must be one of SKIP, UPDATE, OVERWRITE_AND_UPDATE, OVERWRITE_AND_UPDATE_NOT_EMPTY

  • Must not be null

trackingPermissionConflictMode

String

The strategy to handle tracking permissions conflicts. For more information see here

  • Must be one of KEEP_EXISTING, OVERWRITE_EXCEPT_EMPTY, OVERWRITE_FULL

  • Must not be null

clearListBeforeImport

Boolean

Whether the list should be emptied before imports.

resubscribeUnsubscribedRecipients

Boolean

If already unsubscribed recipients should be resubscribed

unsubscribeSubscribedRecipients

Boolean

If already subscribed recipients should be unsubscribed

ignoreUnknownRecipients

Boolean

If recipients that should not known should not be imported

targetList

Number

The list in which the recipients should be imported

targetListTab

String

The target list tab

  • Must be one of SUBSCRIBED, UNSUBSCRIBED, NONE

  • Must not be null

targetFiletype

String

The type of the file that should be imported.

  • Must be one of CSV, XLS

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "trackingPermissionColumnName" : "TrackingPermissionColumnName",
  "trackingPermissionConflictMode" : "KEEP_EXISTING",
  "targetListTab" : "NONE",
  "textDelimiterEscaping" : "DOUBLE",
  "trackingPermissionGrantedValue" : "true",
  "thousandsSeparator" : ".",
  "booleanMatchValue" : true,
  "encoding" : "UTF-8",
  "notifyOnSuccess" : true,
  "clearListBeforeImport" : true,
  "dateTimeFormat" : "dd.MM.yyyy HH:mm:ss",
  "targetFiletype" : "CSV",
  "dateFormat" : "dd.MM.yyyy",
  "timeFormat" : "HH:mm:ss",
  "booleanParserPattern" : "Yes",
  "targetList" : 1,
  "importConflictMode" : "SKIP",
  "emailAddressColumn" : "EmailAddressColumnValue",
  "columnSeparator" : ",",
  "notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
  "notifyOnFailure" : true,
  "resubscribeUnsubscribedRecipients" : true,
  "timezone" : "UTC",
  "decimalSeparator" : ",",
  "notifyOnCancel" : true,
  "ignoreUnknownRecipients" : true,
  "unsubscribeSubscribedRecipients" : true,
  "textDelimiter" : "'"
}'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/0
Content-Type: application/hal+json
Content-Length: 1164

{
  "decimalSeparator" : ",",
  "encoding" : "UTF-8",
  "dateFormat" : "dd.MM.yyyy",
  "booleanMatchValue" : true,
  "dateTimeFormat" : "dd.MM.yyyy HH:mm:ss",
  "timeFormat" : "HH:mm:ss",
  "thousandsSeparator" : ".",
  "booleanParserPattern" : "Yes",
  "timezone" : "UTC",
  "columnSeparator" : ",",
  "textDelimiter" : "'",
  "textDelimiterEscaping" : "DOUBLE",
  "id" : 0,
  "trackingPermissionConflictMode" : "KEEP_EXISTING",
  "importConflictMode" : "SKIP",
  "trackingPermissionGrantedValue" : "true",
  "clearListBeforeImport" : true,
  "unsubscribeSubscribedRecipients" : true,
  "ignoreUnknownRecipients" : true,
  "targetList" : 1,
  "targetListTab" : "NONE",
  "targetFiletype" : "CSV",
  "notifyOnSuccess" : true,
  "emailAddressColumn" : "EmailAddressColumnValue",
  "trackingPermissionColumnName" : "TrackingPermissionColumnName",
  "notifyOnFailure" : true,
  "notifyOnCancel" : true,
  "notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
  "resubscribeUnsubscribedRecipients" : true,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/0"
    }
  }
}

Edit a configuration

A PUT request with the following payload structure as described will update an existing configuration with the specified values. Violations of the constraints will lead to validation errors.

Payload structure

Path Type Description Constraints

emailAddressColumn

String

The name of the column in the csv file that contains the recipient’s email address.

  • Must match the regular expression [a-zA-Z0-9_-]+

  • Must not be null

trackingPermissionColumnName

String

The name of the column in the csv file that contains the information about the tracking permissions.

  • Must not be null

notifyOnSuccess

Boolean

If an email should be sent upon a successful import, to the addresses defined in notifyRecipients.

notifyOnFailure

Boolean

If an email should be sent upon a failed import, to the addresses defined in notifyRecipients.

notifyOnCancel

Boolean

If an email should be sent upon a canceled import, to the addresses defined in notifyRecipients.

notifyRecipients

Array

The list of email addresses that should be notified on success, failure, or cancellation of an import, if enabled.

  • Must not be null

columnSeparator

String

The character which is used to separate the columns.

textDelimiter

String

The character used to separate text fields.

textDelimiterEscaping

String

The character used to escape the text delimeter

dateTimeFormat

String

The date-time format used to parse the date-time columns

dateFormat

String

The date format used to parse the date columns

timeFormat

String

The time format used to parse the time columns

thousandsSeparator

String

The character which is used to to group digits in large numbers for better readability.

  • Must be one of ., ,, _, , '

decimalSeparator

String

The character which is used to separate the integer part from the fractional part of a number.

encoding

String

The encoding of the import file.

booleanParserPattern

String

The pattern which is used to parse text to boolean values.

booleanMatchValue

Boolean

In which boolean value texts should be parsed that match the booleanParsePattern.

trackingPermissionGrantedValue

String

The pattern which indicates that a recipient has tracking permissions.

  • Must not be null

timezone

String

The Time Zone for the Date Time values

importConflictMode

String

The strategy to handle import conflicts. For more information see here

  • Must be one of SKIP, UPDATE, OVERWRITE_AND_UPDATE, OVERWRITE_AND_UPDATE_NOT_EMPTY

  • Must not be null

trackingPermissionConflictMode

String

The strategy to handle tracking permissions conflicts. For more information see here

  • Must be one of KEEP_EXISTING, OVERWRITE_EXCEPT_EMPTY, OVERWRITE_FULL

  • Must not be null

clearListBeforeImport

Boolean

Whether the list should be emptied before imports.

resubscribeUnsubscribedRecipients

Boolean

If already unsubscribed recipients should be resubscribed

unsubscribeSubscribedRecipients

Boolean

If already subscribed recipients should be unsubscribed

ignoreUnknownRecipients

Boolean

If recipients that should not known should not be imported

targetList

Number

The list in which the recipients should be imported

targetListTab

String

The target list tab

  • Must be one of SUBSCRIBED, UNSUBSCRIBED, NONE

  • Must not be null

targetFiletype

String

The type of the file that should be imported.

  • Must be one of CSV, XLS

Examples

csv
Request
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/12' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '{
  "trackingPermissionColumnName" : "TrackingPermissionColumnName",
  "trackingPermissionConflictMode" : "KEEP_EXISTING",
  "targetListTab" : "NONE",
  "textDelimiterEscaping" : "DOUBLE",
  "trackingPermissionGrantedValue" : "true",
  "thousandsSeparator" : ".",
  "booleanMatchValue" : true,
  "encoding" : "UTF-8",
  "notifyOnSuccess" : true,
  "clearListBeforeImport" : true,
  "dateTimeFormat" : "dd.MM.yyyy HH:mm:ss",
  "targetFiletype" : "CSV",
  "dateFormat" : "dd.MM.yyyy",
  "timeFormat" : "HH:mm:ss",
  "booleanParserPattern" : "Yes",
  "targetList" : 1,
  "importConflictMode" : "SKIP",
  "emailAddressColumn" : "EmailAddressColumnValue",
  "columnSeparator" : ",",
  "notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
  "notifyOnFailure" : true,
  "resubscribeUnsubscribedRecipients" : true,
  "timezone" : "UTC",
  "decimalSeparator" : ",",
  "notifyOnCancel" : true,
  "ignoreUnknownRecipients" : true,
  "unsubscribeSubscribedRecipients" : true,
  "textDelimiter" : "'"
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1165

{
  "decimalSeparator" : ",",
  "encoding" : "UTF-8",
  "dateFormat" : "dd.MM.yyyy",
  "booleanMatchValue" : true,
  "dateTimeFormat" : "dd.MM.yyyy HH:mm:ss",
  "timeFormat" : "HH:mm:ss",
  "thousandsSeparator" : ".",
  "booleanParserPattern" : "Yes",
  "timezone" : "UTC",
  "columnSeparator" : ",",
  "textDelimiter" : "'",
  "textDelimiterEscaping" : "DOUBLE",
  "id" : 0,
  "trackingPermissionConflictMode" : "KEEP_EXISTING",
  "importConflictMode" : "SKIP",
  "trackingPermissionGrantedValue" : "true",
  "clearListBeforeImport" : true,
  "unsubscribeSubscribedRecipients" : true,
  "ignoreUnknownRecipients" : true,
  "targetList" : 1,
  "targetListTab" : "NONE",
  "targetFiletype" : "CSV",
  "notifyOnSuccess" : true,
  "emailAddressColumn" : "EmailAddressColumnValue",
  "trackingPermissionColumnName" : "TrackingPermissionColumnName",
  "notifyOnFailure" : true,
  "notifyOnCancel" : true,
  "notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
  "resubscribeUnsubscribedRecipients" : true,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/12"
    }
  }
}

xls

$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/12' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '{
  "targetFiletype" : "XLS",
  "trackingPermissionColumnName" : "TrackingPermissionColumnName",
  "trackingPermissionConflictMode" : "KEEP_EXISTING",
  "targetListTab" : "NONE",
  "targetList" : 1,
  "importConflictMode" : "SKIP",
  "emailAddressColumn" : "EmailAddressColumnValue",
  "trackingPermissionGrantedValue" : "true",
  "thousandsSeparator" : ".",
  "notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
  "resubscribeUnsubscribedRecipients" : true,
  "notifyOnFailure" : true,
  "notifyOnCancel" : true,
  "ignoreUnknownRecipients" : true,
  "notifyOnSuccess" : true,
  "unsubscribeSubscribedRecipients" : true,
  "clearListBeforeImport" : true
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 803

{
  "id" : 0,
  "trackingPermissionConflictMode" : "KEEP_EXISTING",
  "importConflictMode" : "SKIP",
  "trackingPermissionGrantedValue" : "true",
  "clearListBeforeImport" : true,
  "unsubscribeSubscribedRecipients" : true,
  "ignoreUnknownRecipients" : true,
  "targetList" : 1,
  "targetListTab" : "NONE",
  "targetFiletype" : "XLS",
  "notifyOnSuccess" : true,
  "emailAddressColumn" : "EmailAddressColumnValue",
  "trackingPermissionColumnName" : "TrackingPermissionColumnName",
  "notifyOnFailure" : true,
  "notifyOnCancel" : true,
  "notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
  "resubscribeUnsubscribedRecipients" : true,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/12"
    }
  }
}

Delete a configuration

DELETE /imports/recipients/configuration-template/{id}

A DELETE request will delete an existing configuration. If the configuration with the given id can’t be found, it will return status code 404.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/12' -i -X DELETE
Response
HTTP/1.1 204 No Content

Retrieve a preview for an import

GET /imports/recipients/preview{?importFileId,configurationTemplateId}

To get a first look how the import will look if you run it with a certain file and a certain configuration, you can GET a preview. Note that the target file types of both the file and the configuration template must match. The following path parameters are required:

Parameter Required Description

importFileId

yes

The id of an existing import file

configurationTemplateId

yes

The id of an existing import configuration

If there is no importFile or configurationTemplate with the given ID the request will result in a 404. if the preview cannot be rendered due to incorrect configuration (for example, unsuitable column separator or non matching targetFileTypes) the request will result in a 400 with a detail message about the error. Mostly you have to update your configuration, or review your imported file for errors. The preview will only contain the first 20 recipients of the import.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/preview?importFileId=12&configurationTemplateId=39' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 485

{
  "preview" : [ {
    "email" : "johnDoe@example.com",
    "score" : 123.5,
    "birthDay" : "1990-05-14",
    "likesIceCream" : true,
    "name" : "John Doe"
  }, {
    "email" : "janeRoe@example.com",
    "score" : 70.3,
    "birthDay" : "1990-12-25",
    "likesIceCream" : false,
    "name" : "Jane Roe"
  } ],
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/preview?importFileId=12&configurationTemplateId=39"
    }
  }
}

Execute the import

POST /imports/recipients/preconfigured{?fileId,configurationId}

To start a preconfigured import with a given configurationTemplate and importFile, you can send a POST request with the following parameters:

Parameter Required Description

fileId

yes

The id of an existing import file

configurationId

yes

The id of an existing import configuration

If there is no importFile or configurationTemplate with the given ID the request will result in a 404. If the targetFileType attribute of the configurationTemplate and the importFile do not match, the request will result in a 400. The result will be a Status Monitor, which you can use to check the current status of the import.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/preconfigured?fileId=14&configurationId=12' -i -X POST
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/imports/recipients/7
Content-Type: application/hal+json
Content-Length: 722

{
  "id" : 7,
  "successCount" : 0,
  "failCount" : 0,
  "state" : "NEW",
  "triggerType" : "API",
  "beginDate" : "2024-11-19T08:47:13Z",
  "endDate" : null,
  "files" : [ {
    "name" : "import.csv",
    "state" : "NEW",
    "currentCount" : 0,
    "successCount" : 0,
    "failedCount" : 0,
    "id" : 12
  } ],
  "targetListId" : null,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/7"
    },
    "inx:files" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/7/files"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Patch import template configuration

A PATCH request with the following payload structure as described will update an existing configuration with the specified values. Violations of the constraints will lead to validation errors.

Payload structure

Path Type Description Constraints

emailAddressColumn

String

The name of the column in the csv file that contains the recipient’s email address.

  • Must match the regular expression [a-zA-Z0-9_-]+

  • Must not be null

trackingPermissionColumnName

String

The name of the column in the csv file that contains the information about the tracking permissions.

  • Must not be null

notifyOnSuccess

Boolean

If an email should be sent upon a successful import, to the addresses defined in notifyRecipients.

notifyOnFailure

Boolean

If an email should be sent upon a failed import, to the addresses defined in notifyRecipients.

notifyOnCancel

Boolean

If an email should be sent upon a canceled import, to the addresses defined in notifyRecipients.

notifyRecipients

Array

The list of email addresses that should be notified on success, failure, or cancellation of an import, if enabled.

  • Must not be null

columnSeparator

String

The character which is used to separate the columns.

  • Must be one of ,, ;,

  • Must not be null

textDelimiter

String

The character used to separate text fields.

  • Must be one of ', "

textDelimiterEscaping

String

The character used to escape the text delimeter

  • Must be one of BACKSLASH, DOUBLE

dateTimeFormat

String

The date-time format used to parse the date-time columns

  • Must be a valid date-time format

  • Must not be null

dateFormat

String

The date format used to parse the date columns

  • Must be a valid date-time format

  • Must not be null

timeFormat

String

The time format used to parse the time columns

  • Must be a valid date-time format

  • Must not be null

thousandsSeparator

String

The character which is used to to group digits in large numbers for better readability.

  • Must be one of ., ,, _, , '

decimalSeparator

String

The character which is used to separate the integer part from the fractional part of a number.

  • Must be one of ., ,

encoding

String

The encoding of the import file.

  • Must be one of ISO-8859-6, ISO-8859-13, Big5, Big5_HKSCS, GB2312, ISO-8859-7, ISO-8859-8, ISO-2022-JP, EUC-KR, ISO-2022-KR, ISO-8859-5, MacArabic, MacCroatian, MacCyrillic, MacGreek, MacHebrew, MacIceland, MacCentralEurope, MacRoman, MacRomania, MacThai, MacTurkish, MacUkraine, ISO-8859-4, KOI8-R, ISO-8859-3, TIS-620, ISO-8859-9, UTF-8, ISO-8859-1, ISO-8859-15, Cp1257, Cp1251, Cp1250, Cp1253, Cp1254, Cp1252, ISO-8859-2

  • Must not be null

booleanParserPattern

String

The pattern which is used to parse text to boolean values.

  • Must not be null

booleanMatchValue

Boolean

In which boolean value texts should be parsed that match the booleanParsePattern.

trackingPermissionGrantedValue

String

The pattern which indicates that a recipient has tracking permissions.

  • Must not be null

timezone

String

The Time Zone for the Date Time values

  • Must be one of Africa/Abidjan, Africa/Accra, Africa/Addis_Ababa, Africa/Algiers, Africa/Asmara, Africa/Asmera, Africa/Bamako, Africa/Bangui, Africa/Banjul, Africa/Bissau, Africa/Blantyre, Africa/Brazzaville, Africa/Bujumbura, Africa/Cairo, Africa/Casablanca, Africa/Ceuta, Africa/Conakry, Africa/Dakar, Africa/Dar_es_Salaam, Africa/Djibouti, Africa/Douala, Africa/El_Aaiun, Africa/Freetown, Africa/Gaborone, Africa/Harare, Africa/Johannesburg, Africa/Juba, Africa/Kampala, Africa/Khartoum, Africa/Kigali, Africa/Kinshasa, Africa/Lagos, Africa/Libreville, Africa/Lome, Africa/Luanda, Africa/Lubumbashi, Africa/Lusaka, Africa/Malabo, Africa/Maputo, Africa/Maseru, Africa/Mbabane, Africa/Mogadishu, Africa/Monrovia, Africa/Nairobi, Africa/Ndjamena, Africa/Niamey, Africa/Nouakchott, Africa/Ouagadougou, Africa/Porto-Novo, Africa/Sao_Tome, Africa/Timbuktu, Africa/Tripoli, Africa/Tunis, Africa/Windhoek, America/Adak, America/Anchorage, America/Anguilla, America/Antigua, America/Araguaina, America/Argentina/Buenos_Aires, America/Argentina/Catamarca, America/Argentina/ComodRivadavia, America/Argentina/Cordoba, America/Argentina/Jujuy, America/Argentina/La_Rioja, America/Argentina/Mendoza, America/Argentina/Rio_Gallegos, America/Argentina/Salta, America/Argentina/San_Juan, America/Argentina/San_Luis, America/Argentina/Tucuman, America/Argentina/Ushuaia, America/Aruba, America/Asuncion, America/Atikokan, America/Atka, America/Bahia, America/Bahia_Banderas, America/Barbados, America/Belem, America/Belize, America/Blanc-Sablon, America/Boa_Vista, America/Bogota, America/Boise, America/Buenos_Aires, America/Cambridge_Bay, America/Campo_Grande, America/Cancun, America/Caracas, America/Catamarca, America/Cayenne, America/Cayman, America/Chicago, America/Chihuahua, America/Coral_Harbour, America/Cordoba, America/Costa_Rica, America/Creston, America/Cuiaba, America/Curacao, America/Danmarkshavn, America/Dawson, America/Dawson_Creek, America/Denver, America/Detroit, America/Dominica, America/Edmonton, America/Eirunepe, America/El_Salvador, America/Ensenada, America/Fort_Nelson, America/Fort_Wayne, America/Fortaleza, America/Glace_Bay, America/Godthab, America/Goose_Bay, America/Grand_Turk, America/Grenada, America/Guadeloupe, America/Guatemala, America/Guayaquil, America/Guyana, America/Halifax, America/Havana, America/Hermosillo, America/Indiana/Indianapolis, America/Indiana/Knox, America/Indiana/Marengo, America/Indiana/Petersburg, America/Indiana/Tell_City, America/Indiana/Vevay, America/Indiana/Vincennes, America/Indiana/Winamac, America/Indianapolis, America/Inuvik, America/Iqaluit, America/Jamaica, America/Jujuy, America/Juneau, America/Kentucky/Louisville, America/Kentucky/Monticello, America/Knox_IN, America/Kralendijk, America/La_Paz, America/Lima, America/Los_Angeles, America/Louisville, America/Lower_Princes, America/Maceio, America/Managua, America/Manaus, America/Marigot, America/Martinique, America/Matamoros, America/Mazatlan, America/Mendoza, America/Menominee, America/Merida, America/Metlakatla, America/Mexico_City, America/Miquelon, America/Moncton, America/Monterrey, America/Montevideo, America/Montreal, America/Montserrat, America/Nassau, America/New_York, America/Nipigon, America/Nome, America/Noronha, America/North_Dakota/Beulah, America/North_Dakota/Center, America/North_Dakota/New_Salem, America/Nuuk, America/Ojinaga, America/Panama, America/Pangnirtung, America/Paramaribo, America/Phoenix, America/Port-au-Prince, America/Port_of_Spain, America/Porto_Acre, America/Porto_Velho, America/Puerto_Rico, America/Punta_Arenas, America/Rainy_River, America/Rankin_Inlet, America/Recife, America/Regina, America/Resolute, America/Rio_Branco, America/Rosario, America/Santa_Isabel, America/Santarem, America/Santiago, America/Santo_Domingo, America/Sao_Paulo, America/Scoresbysund, America/Shiprock, America/Sitka, America/St_Barthelemy, America/St_Johns, America/St_Kitts, America/St_Lucia, America/St_Thomas, America/St_Vincent, America/Swift_Current, America/Tegucigalpa, America/Thule, America/Thunder_Bay, America/Tijuana, America/Toronto, America/Tortola, America/Vancouver, America/Virgin, America/Whitehorse, America/Winnipeg, America/Yakutat, America/Yellowknife, Antarctica/Casey, Antarctica/Davis, Antarctica/DumontDUrville, Antarctica/Macquarie, Antarctica/Mawson, Antarctica/McMurdo, Antarctica/Palmer, Antarctica/Rothera, Antarctica/South_Pole, Antarctica/Syowa, Antarctica/Troll, Antarctica/Vostok, Arctic/Longyearbyen, Asia/Aden, Asia/Almaty, Asia/Amman, Asia/Anadyr, Asia/Aqtau, Asia/Aqtobe, Asia/Ashgabat, Asia/Ashkhabad, Asia/Atyrau, Asia/Baghdad, Asia/Bahrain, Asia/Baku, Asia/Bangkok, Asia/Barnaul, Asia/Beirut, Asia/Bishkek, Asia/Brunei, Asia/Calcutta, Asia/Chita, Asia/Choibalsan, Asia/Chongqing, Asia/Chungking, Asia/Colombo, Asia/Dacca, Asia/Damascus, Asia/Dhaka, Asia/Dili, Asia/Dubai, Asia/Dushanbe, Asia/Famagusta, Asia/Gaza, Asia/Harbin, Asia/Hebron, Asia/Ho_Chi_Minh, Asia/Hong_Kong, Asia/Hovd, Asia/Irkutsk, Asia/Istanbul, Asia/Jakarta, Asia/Jayapura, Asia/Jerusalem, Asia/Kabul, Asia/Kamchatka, Asia/Karachi, Asia/Kashgar, Asia/Kathmandu, Asia/Katmandu, Asia/Khandyga, Asia/Kolkata, Asia/Krasnoyarsk, Asia/Kuala_Lumpur, Asia/Kuching, Asia/Kuwait, Asia/Macao, Asia/Macau, Asia/Magadan, Asia/Makassar, Asia/Manila, Asia/Muscat, Asia/Nicosia, Asia/Novokuznetsk, Asia/Novosibirsk, Asia/Omsk, Asia/Oral, Asia/Phnom_Penh, Asia/Pontianak, Asia/Pyongyang, Asia/Qatar, Asia/Qostanay, Asia/Qyzylorda, Asia/Rangoon, Asia/Riyadh, Asia/Saigon, Asia/Sakhalin, Asia/Samarkand, Asia/Seoul, Asia/Shanghai, Asia/Singapore, Asia/Srednekolymsk, Asia/Taipei, Asia/Tashkent, Asia/Tbilisi, Asia/Tehran, Asia/Tel_Aviv, Asia/Thimbu, Asia/Thimphu, Asia/Tokyo, Asia/Tomsk, Asia/Ujung_Pandang, Asia/Ulaanbaatar, Asia/Ulan_Bator, Asia/Urumqi, Asia/Ust-Nera, Asia/Vientiane, Asia/Vladivostok, Asia/Yakutsk, Asia/Yangon, Asia/Yekaterinburg, Asia/Yerevan, Atlantic/Azores, Atlantic/Bermuda, Atlantic/Canary, Atlantic/Cape_Verde, Atlantic/Faeroe, Atlantic/Faroe, Atlantic/Jan_Mayen, Atlantic/Madeira, Atlantic/Reykjavik, Atlantic/South_Georgia, Atlantic/St_Helena, Atlantic/Stanley, Australia/ACT, Australia/Adelaide, Australia/Brisbane, Australia/Broken_Hill, Australia/Canberra, Australia/Currie, Australia/Darwin, Australia/Eucla, Australia/Hobart, Australia/LHI, Australia/Lindeman, Australia/Lord_Howe, Australia/Melbourne, Australia/NSW, Australia/North, Australia/Perth, Australia/Queensland, Australia/South, Australia/Sydney, Australia/Tasmania, Australia/Victoria, Australia/West, Australia/Yancowinna, Brazil/Acre, Brazil/DeNoronha, Brazil/East, Brazil/West, CET, CST6CDT, Canada/Atlantic, Canada/Central, Canada/Eastern, Canada/Mountain, Canada/Newfoundland, Canada/Pacific, Canada/Saskatchewan, Canada/Yukon, Chile/Continental, Chile/EasterIsland, Cuba, EET, EST5EDT, Egypt, Eire, Etc/GMT, Etc/GMT+0, Etc/GMT+1, Etc/GMT+10, Etc/GMT+11, Etc/GMT+12, Etc/GMT+2, Etc/GMT+3, Etc/GMT+4, Etc/GMT+5, Etc/GMT+6, Etc/GMT+7, Etc/GMT+8, Etc/GMT+9, Etc/GMT-0, Etc/GMT-1, Etc/GMT-10, Etc/GMT-11, Etc/GMT-12, Etc/GMT-13, Etc/GMT-14, Etc/GMT-2, Etc/GMT-3, Etc/GMT-4, Etc/GMT-5, Etc/GMT-6, Etc/GMT-7, Etc/GMT-8, Etc/GMT-9, Etc/GMT0, Etc/Greenwich, Etc/UCT, Etc/UTC, Etc/Universal, Etc/Zulu, Europe/Amsterdam, Europe/Andorra, Europe/Astrakhan, Europe/Athens, Europe/Belfast, Europe/Belgrade, Europe/Berlin, Europe/Bratislava, Europe/Brussels, Europe/Bucharest, Europe/Budapest, Europe/Busingen, Europe/Chisinau, Europe/Copenhagen, Europe/Dublin, Europe/Gibraltar, Europe/Guernsey, Europe/Helsinki, Europe/Isle_of_Man, Europe/Istanbul, Europe/Jersey, Europe/Kaliningrad, Europe/Kiev, Europe/Kirov, Europe/Lisbon, Europe/Ljubljana, Europe/London, Europe/Luxembourg, Europe/Madrid, Europe/Malta, Europe/Mariehamn, Europe/Minsk, Europe/Monaco, Europe/Moscow, Europe/Nicosia, Europe/Oslo, Europe/Paris, Europe/Podgorica, Europe/Prague, Europe/Riga, Europe/Rome, Europe/Samara, Europe/San_Marino, Europe/Sarajevo, Europe/Saratov, Europe/Simferopol, Europe/Skopje, Europe/Sofia, Europe/Stockholm, Europe/Tallinn, Europe/Tirane, Europe/Tiraspol, Europe/Ulyanovsk, Europe/Uzhgorod, Europe/Vaduz, Europe/Vatican, Europe/Vienna, Europe/Vilnius, Europe/Volgograd, Europe/Warsaw, Europe/Zagreb, Europe/Zaporozhye, Europe/Zurich, GB, GB-Eire, GMT, GMT0, Greenwich, Hongkong, Iceland, Indian/Antananarivo, Indian/Chagos, Indian/Christmas, Indian/Cocos, Indian/Comoro, Indian/Kerguelen, Indian/Mahe, Indian/Maldives, Indian/Mauritius, Indian/Mayotte, Indian/Reunion, Iran, Israel, Jamaica, Japan, Kwajalein, Libya, MET, MST7MDT, Mexico/BajaNorte, Mexico/BajaSur, Mexico/General, NZ, NZ-CHAT, Navajo, PRC, PST8PDT, Pacific/Apia, Pacific/Auckland, Pacific/Bougainville, Pacific/Chatham, Pacific/Chuuk, Pacific/Easter, Pacific/Efate, Pacific/Enderbury, Pacific/Fakaofo, Pacific/Fiji, Pacific/Funafuti, Pacific/Galapagos, Pacific/Gambier, Pacific/Guadalcanal, Pacific/Guam, Pacific/Honolulu, Pacific/Johnston, Pacific/Kanton, Pacific/Kiritimati, Pacific/Kosrae, Pacific/Kwajalein, Pacific/Majuro, Pacific/Marquesas, Pacific/Midway, Pacific/Nauru, Pacific/Niue, Pacific/Norfolk, Pacific/Noumea, Pacific/Pago_Pago, Pacific/Palau, Pacific/Pitcairn, Pacific/Pohnpei, Pacific/Ponape, Pacific/Port_Moresby, Pacific/Rarotonga, Pacific/Saipan, Pacific/Samoa, Pacific/Tahiti, Pacific/Tarawa, Pacific/Tongatapu, Pacific/Truk, Pacific/Wake, Pacific/Wallis, Pacific/Yap, Poland, Portugal, ROK, Singapore, SystemV/AST4, SystemV/AST4ADT, SystemV/CST6, SystemV/CST6CDT, SystemV/EST5, SystemV/EST5EDT, SystemV/HST10, SystemV/MST7, SystemV/MST7MDT, SystemV/PST8, SystemV/PST8PDT, SystemV/YST9, SystemV/YST9YDT, Turkey, UCT, US/Alaska, US/Aleutian, US/Arizona, US/Central, US/East-Indiana, US/Eastern, US/Hawaii, US/Indiana-Starke, US/Michigan, US/Mountain, US/Pacific, US/Samoa, UTC, Universal, W-SU, WET, Zulu, EST, HST, MST, ACT, AET, AGT, ART, AST, BET, BST, CAT, CNT, CST, CTT, EAT, ECT, IET, IST, JST, MIT, NET, NST, PLT, PNT, PRT, PST, SST, VST

  • Must not be null

importConflictMode

String

The strategy to handle import conflicts. For more information see here

  • Must be one of SKIP, UPDATE, OVERWRITE_AND_UPDATE, OVERWRITE_AND_UPDATE_NOT_EMPTY

  • Must not be null

trackingPermissionConflictMode

String

The strategy to handle tracking permissions conflicts. For more information see here

  • Must be one of KEEP_EXISTING, OVERWRITE_EXCEPT_EMPTY, OVERWRITE_FULL

  • Must not be null

clearListBeforeImport

Boolean

Whether the list should be emptied before imports.

resubscribeUnsubscribedRecipients

Boolean

If already unsubscribed recipients should be resubscribed

unsubscribeSubscribedRecipients

Boolean

If already subscribed recipients should be unsubscribed

ignoreUnknownRecipients

Boolean

If recipients that should not known should not be imported

targetList

Number

The list in which the recipients should be imported

targetListTab

String

The target list tab

  • Must be one of SUBSCRIBED, UNSUBSCRIBED, NONE

  • Must not be null

Examples

csv
Request
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/12' -i -X PATCH \
    -H 'Content-Type: application/merge-patch+json' \
    -d '{
  "emailAddressColumn" : "EmailAddressColumnValue",
  "trackingPermissionColumnName" : "TrackingPermissionColumnName",
  "notifyOnSuccess" : true,
  "notifyOnFailure" : true,
  "notifyOnCancel" : true,
  "notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
  "columnSeparator" : ",",
  "textDelimiter" : "'",
  "textDelimiterEscaping" : "DOUBLE",
  "dateTimeFormat" : "dd.MM.yyyy HH:mm:ss",
  "dateFormat" : "dd.MM.yyyy",
  "timeFormat" : "HH:mm:ss",
  "thousandsSeparator" : ".",
  "decimalSeparator" : ",",
  "encoding" : "UTF-8",
  "booleanParserPattern" : "Yes",
  "booleanMatchValue" : true,
  "trackingPermissionGrantedValue" : "true",
  "importConflictMode" : "SKIP",
  "trackingPermissionConflictMode" : "KEEP_EXISTING",
  "clearListBeforeImport" : true,
  "resubscribeUnsubscribedRecipients" : true,
  "unsubscribeSubscribedRecipients" : true,
  "ignoreUnknownRecipients" : true,
  "targetList" : 1,
  "targetListTab" : "NONE",
  "timezone" : "UTC"
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1165

{
  "decimalSeparator" : ",",
  "encoding" : "UTF-8",
  "dateFormat" : "dd.MM.yyyy",
  "booleanMatchValue" : true,
  "dateTimeFormat" : "dd.MM.yyyy HH:mm:ss",
  "timeFormat" : "HH:mm:ss",
  "thousandsSeparator" : ".",
  "booleanParserPattern" : "Yes",
  "timezone" : "UTC",
  "columnSeparator" : ",",
  "textDelimiter" : "'",
  "textDelimiterEscaping" : "DOUBLE",
  "id" : 0,
  "trackingPermissionConflictMode" : "KEEP_EXISTING",
  "importConflictMode" : "SKIP",
  "trackingPermissionGrantedValue" : "true",
  "clearListBeforeImport" : true,
  "unsubscribeSubscribedRecipients" : true,
  "ignoreUnknownRecipients" : true,
  "targetList" : 1,
  "targetListTab" : "NONE",
  "targetFiletype" : "CSV",
  "notifyOnSuccess" : true,
  "emailAddressColumn" : "EmailAddressColumnValue",
  "trackingPermissionColumnName" : "TrackingPermissionColumnName",
  "notifyOnFailure" : true,
  "notifyOnCancel" : true,
  "notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
  "resubscribeUnsubscribedRecipients" : true,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/12"
    }
  }
}

xls

$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/12' -i -X PATCH \
    -H 'Content-Type: application/merge-patch+json' \
    -d '{
  "emailAddressColumn" : "EmailAddressColumnValue",
  "trackingPermissionColumnName" : "TrackingPermissionColumnName",
  "notifyOnSuccess" : true,
  "notifyOnFailure" : true,
  "notifyOnCancel" : true,
  "notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
  "thousandsSeparator" : ".",
  "trackingPermissionGrantedValue" : "true",
  "importConflictMode" : "SKIP",
  "trackingPermissionConflictMode" : "KEEP_EXISTING",
  "clearListBeforeImport" : true,
  "resubscribeUnsubscribedRecipients" : true,
  "unsubscribeSubscribedRecipients" : true,
  "ignoreUnknownRecipients" : true,
  "targetList" : 1,
  "targetListTab" : "NONE"
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 803

{
  "id" : 0,
  "trackingPermissionConflictMode" : "KEEP_EXISTING",
  "importConflictMode" : "SKIP",
  "trackingPermissionGrantedValue" : "true",
  "clearListBeforeImport" : true,
  "unsubscribeSubscribedRecipients" : true,
  "ignoreUnknownRecipients" : true,
  "targetList" : 1,
  "targetListTab" : "NONE",
  "targetFiletype" : "XLS",
  "notifyOnSuccess" : true,
  "emailAddressColumn" : "EmailAddressColumnValue",
  "trackingPermissionColumnName" : "TrackingPermissionColumnName",
  "notifyOnFailure" : true,
  "notifyOnCancel" : true,
  "notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
  "resubscribeUnsubscribedRecipients" : true,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/12"
    }
  }
}

Bounces

‘Bounces’ are emails that are returned to the sender because they could not be delivered for some reason.

Inxmail Professional automatically assigns all bounces to specific categories ('hard_bounce', 'soft_bounce', 'unknown_bounce').

Bounce category

Every bounce has one of the following category:

Bounce category Description

SOFT

Soft bounces generally exist if there are temporary errors associated with the delivery on the recipient side. This is the case with full email inboxes, for example.

HARD

Hard bounces generally exist if there are permanent errors associated with the delivery on the recipient side. This is the case with invalid email addresses, for example.

UNKNOWN

Unknown bounces generally exist if the mail could not be categorized by inxmail.

Retrieve single bounce

GET /bounces/{id}

A GET request with an ID parameter will return the requested bounce.

Request structure

Table 48. /customer/rest/v1/bounces/{id}
Parameter Description

id

The ID of the bounce

Response structure

Path Type Description

id

Number

The ID of the bounce

listId

Number

The ID of the associated list

mailingId

Number

The ID of the associated mailing

bounceCategory

String

The category of the bounce

matchedEmailAddress

String

The email address for which the bounce occured

recipientId

Number

The ID of the recipient

sendingId

Number

The ID of the sending

timestamp

String

The point in time when this bounce was processed

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/bounces/1' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 661

{
  "id" : 1,
  "timestamp" : "2024-11-19T08:47:01Z",
  "listId" : 2,
  "recipientId" : 4,
  "mailingId" : 3,
  "bounceCategory" : "HARD",
  "matchedEmailAddress" : "john.doe@example.com",
  "sendingId" : 5,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/bounces/1"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/2"
    },
    "inx:recipient" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/4"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve bounce collection

GET /bounces{?startDate,endDate,embedded,bounceCategory,listId,mailingId,sendingIds,recipientAttributes}

or

GET /bounces{?startDate,endDate,embedded,bounceCategory,mailingIds,sendingIds,listIds,recipientAttributes}

A GET request on the bounces resource will return the first page of bounces.

Request parameters

Parameter Required Description

startDate

no

The start date (inclusive) for the desired bounces

endDate

no

The end date (exclusive) for the desired bounces

bounceCategory

no

The bounceCategory for the desired bounces. Default is all bounceCategories.

listId

no

The ID of the list to retrieve bounces for

embedded

no

Indicates the relations of the resources that should be embedded in the result.

recipientAttributes

no

Indicates the names of the recipient attributes that should be included in the embedded recipient result. More than one value can be specified with multiple query parameters or comma separated list.

mailingId

no

The ID of the mailing to retrieve bounces for.

sendingIds

no

The IDs of the sendings to retrieve bounces for.

mailingIds

no

The IDs of the mailings to retrieve bounces for. This parameter must not be specified at the same time as mailingId.

listIds

no

The IDs of the lists to retrieve bounces for. This parameter must not be specified at the same time as listId.

Embeddable relations

Relation Description

inx:recipient

The recipient that is associated to this bounce, if known.

Response structure

See section pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/bounces?startDate=2024-11-19T07:47:02Z&endDate=2024-11-19T09:47:02Z&embedded=inx:recipient&bounceCategory=HARD,SOFT,UNKNOWN&listId=3&mailingId=4&sendingIds=5,6&recipientAttributes=firstName,lastName' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 5043

{
  "_embedded" : {
    "inx:bounces" : [ {
      "id" : 1,
      "timestamp" : null,
      "listId" : 2,
      "recipientId" : 4,
      "mailingId" : 3,
      "bounceCategory" : "SOFT",
      "matchedEmailAddress" : "john.doe_1@example.com",
      "sendingId" : 5,
      "_embedded" : {
        "inx:recipient" : {
          "id" : 4,
          "attributes" : {
            "firstName" : "John",
            "lastName" : "Doe"
          },
          "email" : "john.doe_4@example.com",
          "lowerEmail" : null,
          "unavailable" : false,
          "last_modified" : "2018-04-17T12:06:14Z",
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/recipients/4?attributes=firstName%2ClastName"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/bounces/1"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/2"
        },
        "inx:recipient" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/4"
        }
      }
    }, {
      "id" : 2,
      "timestamp" : null,
      "listId" : 3,
      "recipientId" : 5,
      "mailingId" : 4,
      "bounceCategory" : "HARD",
      "matchedEmailAddress" : "john.doe_2@example.com",
      "sendingId" : 6,
      "_embedded" : {
        "inx:recipient" : {
          "id" : 5,
          "attributes" : {
            "firstName" : "John",
            "lastName" : "Doe"
          },
          "email" : "john.doe_5@example.com",
          "lowerEmail" : null,
          "unavailable" : false,
          "last_modified" : "2018-04-17T12:06:14Z",
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5?attributes=firstName%2ClastName"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/bounces/2"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        },
        "inx:recipient" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5"
        }
      }
    }, {
      "id" : 3,
      "timestamp" : null,
      "listId" : 4,
      "recipientId" : 6,
      "mailingId" : 5,
      "bounceCategory" : "SOFT",
      "matchedEmailAddress" : "john.doe_3@example.com",
      "sendingId" : 7,
      "_embedded" : {
        "inx:recipient" : {
          "id" : 6,
          "attributes" : {
            "firstName" : "John",
            "lastName" : "Doe"
          },
          "email" : "john.doe_6@example.com",
          "lowerEmail" : null,
          "unavailable" : false,
          "last_modified" : "2018-04-17T12:06:14Z",
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/recipients/6?attributes=firstName%2ClastName"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/bounces/3"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/4"
        },
        "inx:recipient" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/6"
        }
      }
    }, {
      "id" : 4,
      "timestamp" : null,
      "listId" : 5,
      "recipientId" : 7,
      "mailingId" : 6,
      "bounceCategory" : "HARD",
      "matchedEmailAddress" : "john.doe_4@example.com",
      "sendingId" : 8,
      "_embedded" : {
        "inx:recipient" : {
          "id" : 7,
          "attributes" : {
            "firstName" : "John",
            "lastName" : "Doe"
          },
          "email" : "john.doe_7@example.com",
          "lowerEmail" : null,
          "unavailable" : false,
          "last_modified" : "2018-04-17T12:06:14Z",
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/recipients/7?attributes=firstName%2ClastName"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/bounces/4"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/5"
        },
        "inx:recipient" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/7"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/bounces?pageSize=-1&embedded=inx%3Arecipient&recipientAttributes=firstName&recipientAttributes=lastName&startDate=2024-11-19T07%3A47%3A02Z&endDate=2024-11-19T09%3A47%3A02Z&bounceCategory=HARD&bounceCategory=SOFT&bounceCategory=UNKNOWN&listId=3&mailingId=4&sendingIds=5&sendingIds=6"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Clicks

A click is a recipient reaction which gets created after a recipient has clicked a link.

If person-based tracking consent setting is active on a certain list, clicks will only show the real recipient ID if the recipient of this click has granted consent to tracking. Otherwise the recipient ID of this click is omitted. The person-based tracking consent can also be turned off on a certain list. In that case the correct recipient ID of a click is always present.

Retrieve single click

GET /clicks/{id}

A GET request with an ID parameter will return the requested click.

Request structure

Table 49. /customer/rest/v1/clicks/{id}
Parameter Description

id

The ID of the click

Response structure

Path Type Description

id

Number

The ID of the click

listId

Number

The ID of the list associated to this click

trackingHash

String

The tracking hash of the click

recipientId

Number

The ID of the recipient associated to this click

linkId

Number

The ID of the link associated to this click

sendingId

Number

The ID of the sending associated to this click

mailingId

Number

The ID of the mailing associated to this click

timestamp

String

The point in time when this click occurred

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/clicks/1' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 848

{
  "id" : 1,
  "timestamp" : "2017-12-27T10:47:48Z",
  "listId" : 3,
  "recipientId" : 1,
  "mailingId" : 5,
  "trackingHash" : "b8c37e33defde51cf91e1e03e51657db",
  "linkId" : 3,
  "sendingId" : 1,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/clicks/1"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
    },
    "inx:mailing" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/5"
    },
    "inx:sending" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings/1"
    },
    "inx:recipient" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/1"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve click collection

GET /clicks{?sendingId,mailingId,trackedOnly,embedded,startDate,endDate,recipientAttributes,listIds}

or

GET /clicks{?sendingId,trackedOnly,embedded,startDate,endDate,recipientAttributes,mailingIds,listIds}

A GET request on the click resource will return the first page of clicks.

Request parameters

Parameter Required Description

mailingId

no

The ID of the mailing to retrieve clicks for

sendingId

no

The ID of the sending to retrieve clicks for

trackedOnly

no

Indicates that only clicks where the recipient who clicked is identifiable will be returned.

embedded

no

Indicates the relations of the resources that should be embedded in the result.

startDate

no

The start date (inclusive) for the desired clicks

endDate

no

The end date (exclusive) for the desired clicks

recipientAttributes

no

Indicates the names of the recipient attributes that should be included in the embedded recipient result. More than one value can be specified with multiple query parameters or comma separated list.

mailingIds

no

The IDs of the mailings to retrieve clicks for. This parameter must not be specified at the same time as mailingId.

listIds

no

The IDs of the lists to retrieve clicks for. This parameter must not be specified at the same time as listId.

Embeddable relations

Relation Description

inx:recipient

The recipient who clicked the link, if known.

Response structure

See section pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/clicks?sendingId=1&mailingId=5&trackedOnly=true&embedded=inx:recipient&startDate=2018-04-17T12:06:14Z&endDate=2018-04-17T13:02:33Z&recipientAttributes=firstName,lastName&listIds=4,6' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 3218

{
  "_embedded" : {
    "inx:clicks" : [ {
      "id" : 1,
      "timestamp" : "2018-04-17T12:06:14Z",
      "listId" : 3,
      "recipientId" : 5,
      "mailingId" : 5,
      "trackingHash" : "b8c37e33defde51cf91e1e03e51657db",
      "linkId" : 11,
      "sendingId" : 1,
      "_embedded" : {
        "inx:recipient" : {
          "id" : 5,
          "attributes" : {
            "firstName" : "John",
            "lastName" : "Doe"
          },
          "email" : "john.doe@example.com",
          "lowerEmail" : null,
          "unavailable" : false,
          "last_modified" : "2018-04-17T12:06:14Z",
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5?attributes=firstName%2ClastName"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/clicks/1"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        },
        "inx:mailing" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/5"
        },
        "inx:sending" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/sendings/1"
        },
        "inx:recipient" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5"
        }
      }
    }, {
      "id" : 2,
      "timestamp" : "2018-04-17T12:08:14Z",
      "listId" : 3,
      "recipientId" : 8,
      "mailingId" : 5,
      "trackingHash" : "b8c1337adefde51cf91e1e03e51657db",
      "linkId" : 11,
      "sendingId" : 1,
      "_embedded" : {
        "inx:recipient" : {
          "id" : 8,
          "attributes" : {
            "firstName" : "Richard",
            "lastName" : "Roe"
          },
          "email" : "richard.roe@example.com",
          "lowerEmail" : null,
          "unavailable" : false,
          "last_modified" : "2018-04-17T12:08:14Z",
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/recipients/8?attributes=firstName%2ClastName"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/clicks/2"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        },
        "inx:mailing" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/5"
        },
        "inx:sending" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/sendings/1"
        },
        "inx:recipient" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/8"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/clicks?pageSize=-1&sendingId=1&mailingId=5&embedded=inx%3Arecipient&trackedOnly=true&recipientAttributes=firstName&recipientAttributes=lastName&startDate=2018-04-17T12%3A06%3A14Z&endDate=2018-04-17T13%3A02%3A33Z&listIds=4&listIds=6"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Web beacon hits

A web beacon is one of various techniques used on web pages or email, to unobtrusively (usually invisibly) allow checking that a user has accessed some content. In Inxmail Professional a web beacon hit is the recipient reaction which gets created after a recipient has opened a mailing and actually has accessed the content of the mailing, e.g. an image in this mailing.

If person-based tracking consent setting is active on a certain list, web beacon hits will only show the real ID and email address of the recipient, but only if the recipient of this web beacon hit has granted consent to tracking. Otherwise the recipient’s ID and email address of this web beacon hit is null. The person-based tracking consent can also be turned off on a certain list. In that case the correct recipient’s ID and email address of a web beacon hit is always present.

Retrieve single web beacon hit

GET /web-beacon-hits/{id}

A GET request with an ID parameter will return the requested web beacon hit.

Request structure

Table 50. /customer/rest/v1/web-beacon-hits/{id}
Parameter Description

id

The ID of the web beacon hit

Response structure

Path Type Description

id

Number

The ID of the web beacon hit

listId

Number

The ID of the list associated to this web beacon hit

trackingHash

String

The tracking hash of the web beacon hit

recipientId

Number

The ID of the recipient associated to this web beacon hit

linkId

Number

The ID of the link associated to this web beacon hit

sendingId

Number

The ID of the sending associated to this web beacon hit

mailingId

Number

The ID of the mailing associated to this web beacon hit

timestamp

String

The point in time when this web beacon hit occurred

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/web-beacon-hits/1' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 857

{
  "id" : 1,
  "timestamp" : "2017-12-27T10:47:48Z",
  "listId" : 3,
  "recipientId" : 1,
  "mailingId" : 5,
  "trackingHash" : "b8c37e33defde51cf91e1e03e51657db",
  "linkId" : 3,
  "sendingId" : 1,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits/1"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
    },
    "inx:mailing" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/mailings/5"
    },
    "inx:sending" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/sendings/1"
    },
    "inx:recipient" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/recipients/1"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve web beacon hits collection

GET /web-beacon-hits{?sendingId,mailingIds,listIds,trackedOnly,embedded,startDate,endDate,recipientAttributes}

A GET request on the web beacon hit resource will return the first page of web beacon hits.

Request parameters

Parameter Required Description

mailingId

no

The ID of the mailing to retrieve clicks for

sendingId

no

The ID of the sending to retrieve clicks for

trackedOnly

no

Indicates that only web beacon hits where the recipient who triggered the hit is identifiable will be returned.

embedded

no

Indicates the relations of the resources that should be embedded in the result.

startDate

no

The start date (inclusive) for the desired clicks

endDate

no

The end date (exclusive) for the desired clicks

recipientAttributes

no

Indicates the names of the recipient attributes that should be included in the embedded recipient result. More than one value can be specified with multiple query parameters or comma separated list.

mailingIds

no

The IDs of the mailings to retrieve clicks for. This parameter must not be specified at the same time as mailingId.

listIds

no

The IDs of the lists to retrieve clicks for. This parameter must not be specified at the same time as listId.

Embeddable relations

Relation Description

inx:recipient

The recipient who triggered the web beacon hit, if known

Response structure

See section pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/web-beacon-hits?sendingId=1&mailingIds=5&listIds=3&trackedOnly=true&embedded=inx:recipient&startDate=2018-04-17T12:06:14Z&endDate=2018-04-17T13:02:33Z&recipientAttributes=firstName,lastName' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 3244

{
  "_embedded" : {
    "inx:web-beacon-hits" : [ {
      "id" : 1,
      "timestamp" : "2018-04-17T12:06:14Z",
      "listId" : 3,
      "recipientId" : 5,
      "mailingId" : 5,
      "trackingHash" : "b8c37e33defde51cf91e1e03e51657db",
      "linkId" : 11,
      "sendingId" : 1,
      "_embedded" : {
        "inx:recipient" : {
          "id" : 5,
          "attributes" : {
            "firstName" : "John",
            "lastName" : "Doe"
          },
          "email" : "john.doe@example.com",
          "lowerEmail" : null,
          "unavailable" : false,
          "last_modified" : "2018-04-17T12:06:14Z",
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5?attributes=firstName%2ClastName"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits/1"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        },
        "inx:mailing" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/5"
        },
        "inx:sending" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/sendings/1"
        },
        "inx:recipient" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/5"
        }
      }
    }, {
      "id" : 2,
      "timestamp" : "2018-04-17T12:08:14Z",
      "listId" : 3,
      "recipientId" : 8,
      "mailingId" : 5,
      "trackingHash" : "b8c1337adefde51cf91e1e03e51657db",
      "linkId" : 11,
      "sendingId" : 1,
      "_embedded" : {
        "inx:recipient" : {
          "id" : 8,
          "attributes" : {
            "firstName" : "Richard",
            "lastName" : "Roe"
          },
          "email" : "richard.roe@example.com",
          "lowerEmail" : null,
          "unavailable" : false,
          "last_modified" : "2018-04-17T12:08:14Z",
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/recipients/8?attributes=firstName%2ClastName"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits/2"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        },
        "inx:mailing" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/mailings/5"
        },
        "inx:sending" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/sendings/1"
        },
        "inx:recipient" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/recipients/8"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/web-beacon-hits?pageSize=1&sendingId=1&embedded=inx%3Arecipient&trackedOnly=true&recipientAttributes=firstName&recipientAttributes=lastName&startDate=2018-04-17T12%3A06%3A14Z&endDate=2018-04-17T13%3A02%3A33Z&listIds=3&mailingIds=5"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Blacklist entries

The blacklist feature in Inxmail Professional is used to block certain recipients from entering the system. The blacklist consists of individual entries each declaring a pattern that matches email addresses to block. Any email address that matches the pattern of one of the blacklist entries will be blocked from entering the system.

A pattern may contain the wildcard character * matching any number of characters. The following table demonstrates this feature with some examples:

Pattern Description

john.doe@example.com

Blocks the address john.doe@example.com

*@example.com

Blocks all addresses under the domain example.com

john.doe@*

Blocks all addresses with a local part of john.doe

Retrieve single blacklist entry

GET /blacklist-entries/{id}

A GET request with a ID parameter will return the requested blacklist entry.

Request structure

Table 51. /customer/rest/v1/blacklist-entries/{id}
Parameter Description

id

The ID of the blacklist entry

Response structure

Path Type Description

id

Number

The ID of the blacklist entry

pattern

String

The pattern for email addresses blocked by this blacklist entry

description

String

A descriptive text for this blacklist entry

modificationDate

String

The last modification date of the blacklist entry

blockedAddressCount

Number

The number of import attempts that were blocked by this blacklist entry

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/blacklist-entries/5' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 304

{
  "id" : 5,
  "pattern" : "john.doe@example.com",
  "description" : "Got a complaint from this recipient",
  "modificationDate" : "2018-09-17T06:24:35Z",
  "blockedAddressCount" : 5,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/blacklist-entries/5"
    }
  }
}

Retrieve blacklist entry collection

GET /blacklist-entries{?lastModifiedSince,patternContainsIgnoreCase}

A GET request on the blacklist entry resource will return the first page of blacklist entries.

Response structure

See section pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/blacklist-entries?lastModifiedSince=2018-01-16T11:42:32Z&patternContainsIgnoreCase=*' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1259

{
  "_embedded" : {
    "inx:blacklist-entries" : [ {
      "id" : 1,
      "pattern" : "john.doe@example.com",
      "description" : "block john doe",
      "modificationDate" : null,
      "blockedAddressCount" : 1,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/blacklist-entries/1"
        }
      }
    }, {
      "id" : 2,
      "pattern" : "*@invalid.com",
      "description" : "block all email addresses ending with @invalid",
      "modificationDate" : null,
      "blockedAddressCount" : 10,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/blacklist-entries/2"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/blacklist-entries?afterId=0&pageSize=2&lastModifiedSince=2018-01-16T11%3A42%3A32Z&patternContainsIgnoreCase=%2A"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/blacklist-entries?afterId=2&pageSize=2&lastModifiedSince=2018-01-16T11%3A42%3A32Z&patternContainsIgnoreCase=%2A"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Delete a single blacklist entry by pattern

DELETE /blacklist-entries{?pattern}

A DELETE request will remove an entry from the blacklist.

Request parameters

Parameter Required Description

pattern

yes

The pattern for email addresses blocked by this blacklist entry which should be deleted.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/blacklist-entries/?pattern=john.doe@example.com' -i -X DELETE
Response
HTTP/1.1 204 No Content

Delete a single blacklist entry by ID

DELETE /blacklist-entries/{id}

A DELETE request will remove an entry from the blacklist.

Request parameters

Unresolved directive in blacklist/structure.adoc - include::/home/jenkins/agent/workspace/est.documentation_release_4.8.68/xpro-rest-impl/build/generated-snippets/delete-existing-blacklist-entry-by-id/request-parameters.adoc[]

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/blacklist-entries/1' -i -X DELETE
Response
HTTP/1.1 204 No Content

Preview a blacklist entry

GET /blacklist-entries/preview{?pattern}

A GET request with a ID parameter will return a preview if the requested blacklist entry.

Request structure

GET /customer/rest/v1/blacklist-entries/preview?pattern=abc HTTP/1.1
Host: api.inxmail.com

Response structure

Path Type Description

affectedRecipients

Number

The number of import attempts that were blocked by this blacklist entry

pattern

String

The pattern for email addresses blocked by this blacklist entry

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/blacklist-entries/preview?pattern=abc' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 205

{
  "affectedRecipients" : 5,
  "pattern" : "john.doe@example.com",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/blacklist-entries/preview?pattern=abc"
    }
  }
}

Create a new blacklist entry

This API provides the possibility to create new blacklist entries. New blacklist entries that are created may not contain the asterisk * character, except that the asterisk is on the beginning or on the end of the pattern.

POST /blacklist-entries

A POST request with the following structure will create a new blacklist entry.

Payload structure

Path Type Description Constraints

pattern

String

The pattern of the new blacklist entry

  • Must not be null

  • Must not contain padding whitespace characters

  • Size must be between 2 and 254 inclusive

description

String

A description to the describe this blacklist entry

  • Size must be between 2 and 254 inclusive

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/blacklist-entries/' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "pattern" : "john.doe@example.com",
  "description" : "Got a complaint from this recipient"
}'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/blacklist-entries/5
Content-Type: application/hal+json
Content-Length: 304

{
  "id" : 5,
  "pattern" : "john.doe@example.com",
  "description" : "Got a complaint from this recipient",
  "modificationDate" : "2012-07-13T02:29:42Z",
  "blockedAddressCount" : 0,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/blacklist-entries/5"
    }
  }
}

Update a blacklist entry

This API provides the possibility to update blacklist entries.

PUT /blacklist-entries/5

A PUT request with the following structure will update the blacklist entry.

Payload structure

Path Type Description Constraints

pattern

String

The pattern of the new blacklist entry

  • Must not be null

  • Must not contain padding whitespace characters

  • Size must be between 2 and 254 inclusive

description

String

A description to describe this blacklist entry

  • Size must be between 2 and 254 inclusive

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/blacklist-entries/5' -i -X PUT \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "pattern" : "john.doe@example.com",
  "description" : "Got a complaint from this recipient"
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 286

{
  "id" : 0,
  "pattern" : "john.doe@example.com",
  "description" : "Got a complaint from this recipient",
  "modificationDate" : null,
  "blockedAddressCount" : 0,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/blacklist-entries/5"
    }
  }
}

Response statistics

The response statistics contains the most important performance data about a mailing.

Response statistics are only available for the following mailing types (see Mailing type):

  • REGULAR_MAILING

  • ACTION_MAILING

  • TIME_TRIGGER_MAILING

  • SPLIT_TEST_MAILING

Retrieve response statistics for a mailing

GET /statistics/responses{?mailingId}

A GET request with an mailing ID parameter will return the requested response statistics.

Request parameters

Parameter Required Description

mailingId

yes

The ID of the mailing

Response structure

Path Type Description

openingRecipients

Number

Number of opening recipients. Opening: First unique click or graphic loaded in the email.

botInteractions

Number

Number of interactions by bots. Interaction: First graphic loaded in the email by a bot.

openingRate

Number

Opening rate: Number of opening recipients / number of net recipients

totalClicks

Number

Total clicks

clickingRecipients

Number

Number of clicking recipients

uniqueClickRate

Number

Unique click rate: Number of clicking recipients / number of net recipients

ctor

Number

CTOR: Number of clicking recipients / number of opening recipients

unsubscribeClicks

Number

Number of unsubscribe clicks

listUnsubscribeClicks

Number

Number of unsubscribe clicks via list unsubscribe

unsubscribeRate

Number

Unsubscribe rate

statisticsByLink

Null

Statistics by each link

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/statistics/responses?mailingId=5' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 455

{
  "openingRecipients" : 125,
  "botInteractions" : 0,
  "openingRate" : 0.4545,
  "totalClicks" : 500,
  "clickingRecipients" : 40,
  "uniqueClickRate" : 0.1454,
  "ctor" : 0.32,
  "unsubscribeClicks" : 100,
  "listUnsubscribeClicks" : 90,
  "unsubscribeRate" : 0.3636,
  "statisticsByLink" : null,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/statistics/responses?mailingId=5&includeLinkData=false"
    }
  }
}

Retrieve response statistics for a mailing with statistics per link

GET /statistics/responses{?mailingId,includeLinkData}

A GET request with an mailing ID parameter and includeLinkData flag set to true will return the requested response statistics with per link details.

Request parameters

Parameter Required Description

mailingId

yes

The ID of the mailing

includeLinkData

no

Include the total clicks and more information for each of links

Response structure

Path Type Description

openingRecipients

Number

Number of opening recipients. Opening: First unique click or graphic loaded in the email.

botInteractions

Number

Number of interactions by bots. Interaction: First graphic loaded in the email by a bot.

openingRate

Number

Opening rate: Number of opening recipients / number of net recipients

totalClicks

Number

Total clicks

clickingRecipients

Number

Number of clicking recipients

uniqueClickRate

Number

Unique click rate: Number of clicking recipients / number of net recipients

ctor

Number

CTOR: Number of clicking recipients / number of opening recipients

unsubscribeClicks

Number

Number of unsubscribe clicks

listUnsubscribeClicks

Number

Number of unsubscribe clicks via list unsubscribe

unsubscribeRate

Number

Unsubscribe rate

statisticsByLink

Array

Statistics by each link

statisticsByLink[].linkId

Number

Id of the link

statisticsByLink[].reportName

String

Report name of the link

statisticsByLink[].linkUrl

String

Url of the link

statisticsByLink[].totalClicks

Number

Amount of total clicks by the link

statisticsByLink[].linkType

String

Type of the link

statisticsByLink[].uniqueClicks

Number

Amount of unique clicks by the link (could be null in case unique click feature is not supported by the LinkType )

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/statistics/responses?mailingId=5&includeLinkData=true' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1772

{
  "openingRecipients" : 1,
  "botInteractions" : 0,
  "openingRate" : 0.5,
  "totalClicks" : 32,
  "clickingRecipients" : 1,
  "uniqueClickRate" : 0.5,
  "ctor" : 1.0,
  "unsubscribeClicks" : 1,
  "listUnsubscribeClicks" : 0,
  "unsubscribeRate" : 0.5,
  "statisticsByLink" : [ {
    "linkId" : 605,
    "linkUrl" : "https://www.inxmail1.com/",
    "reportName" : "ReportName1",
    "linkType" : "UNSUBSCRIBE_HEADER_LINK",
    "uniqueClicks" : 0,
    "totalClicks" : 0
  }, {
    "linkId" : 606,
    "linkUrl" : "https://www.inxmail2.com/",
    "reportName" : "ReportName2",
    "linkType" : "UNIQUE_COUNT",
    "uniqueClicks" : 1,
    "totalClicks" : 3
  }, {
    "linkId" : 607,
    "linkUrl" : "https://www.inxmail3.com/",
    "reportName" : "ReportName1",
    "linkType" : "COUNT",
    "uniqueClicks" : 1,
    "totalClicks" : 4
  }, {
    "linkId" : 608,
    "linkUrl" : "https://www.inxmail4.com/",
    "reportName" : "ReportName4",
    "linkType" : "UNSUBSCRIBE_LINK",
    "uniqueClicks" : 1,
    "totalClicks" : 4
  }, {
    "linkId" : 609,
    "linkUrl" : "https://www.inxmail5.com/",
    "reportName" : "ReportName5",
    "linkType" : "UNSUBSCRIBE_PAGE",
    "uniqueClicks" : 1,
    "totalClicks" : 5
  }, {
    "linkId" : 610,
    "linkUrl" : "https://www.inxmail6.com/",
    "reportName" : "ReportName6",
    "linkType" : "GRANT_TRACKING_PERMISSION",
    "uniqueClicks" : 1,
    "totalClicks" : 6
  }, {
    "linkId" : 611,
    "linkUrl" : "https://www.inxmail7.com/",
    "reportName" : "ReportName7",
    "linkType" : "WITHDRAW_TRACKING_PERMISSION",
    "uniqueClicks" : 1,
    "totalClicks" : 10
  } ],
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/statistics/responses?mailingId=5&includeLinkData=true"
    }
  }
}

Retrieve response statistics for a mailing with statistics per link and clicksByType

A GET request with an mailing ID parameter and includeLinkData set to true and includeTypeData will return the requested response statistics with per link details and clicks split by type.

Request parameters

Parameter Required Description

mailingId

yes

The ID of the mailing

includeLinkData

no

Include the total clicks and more information for each of links

includeTypeData

no

Include the clicks by type data, includeLinkData must be true

Response structure

Path Type Description

openingRecipients

Number

Number of opening recipients. Opening: First unique click or graphic loaded in the email.

botInteractions

Number

Number of interactions by bots. Interaction: First graphic loaded in the email by a bot.

openingRate

Number

Opening rate: Number of opening recipients / number of net recipients

totalClicks

Number

Total clicks

clickingRecipients

Number

Number of clicking recipients

uniqueClickRate

Number

Unique click rate: Number of clicking recipients / number of net recipients

ctor

Number

CTOR: Number of clicking recipients / number of opening recipients

unsubscribeClicks

Number

Number of unsubscribe clicks

listUnsubscribeClicks

Number

Number of unsubscribe clicks via list unsubscribe

unsubscribeRate

Number

Unsubscribe rate

statisticsByLink

Array

Statistics by each link

statisticsByLink[].linkId

Number

Id of the link

statisticsByLink[].reportName

String

Report name of the link

statisticsByLink[].linkUrl

String

Url of the link

statisticsByLink[].totalClicks

Number

Amount of total clicks by the link

statisticsByLink[].linkType

String

Type of the link

statisticsByLink[].uniqueClicks

Number

Amount of unique clicks by the link (could be null in case unique click feature is not supported by the LinkType )

statisticsByLink[].clicksByType

Array

Clicks by type

statisticsByLink[].clicksByType[].type

String

Type of client where the click was made, can be: MOBILE, DESKTOP, WEB, AMBIGUOUS OR UNKOWN

statisticsByLink[].clicksByType[].totalClicks

Number

Total clicks of this type

statisticsByLink[].clicksByType[].uniqueClicks

Number

Unique clicks of this type

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/statistics/responses?mailingId=5&includeLinkData=true&includeTypeData=true' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1107

{
  "openingRecipients" : 1,
  "botInteractions" : 0,
  "openingRate" : 0.5,
  "totalClicks" : 32,
  "clickingRecipients" : 1,
  "uniqueClickRate" : 0.5,
  "ctor" : 1.0,
  "unsubscribeClicks" : 1,
  "listUnsubscribeClicks" : 0,
  "unsubscribeRate" : 0.5,
  "statisticsByLink" : [ {
    "linkId" : 605,
    "linkUrl" : "https://www.inxmail1.com/",
    "reportName" : "ReportName1",
    "linkType" : "UNSUBSCRIBE_HEADER_LINK",
    "uniqueClicks" : 0,
    "totalClicks" : 0,
    "clicksByType" : [ {
      "type" : "DESKTOP",
      "totalClicks" : 10,
      "uniqueClicks" : 5
    }, {
      "type" : "MOBILE",
      "totalClicks" : 20,
      "uniqueClicks" : 10
    }, {
      "type" : "WEB",
      "totalClicks" : 20,
      "uniqueClicks" : 10
    }, {
      "type" : "AMBIGUOUS",
      "totalClicks" : 20,
      "uniqueClicks" : 10
    }, {
      "type" : "UNKOWN",
      "totalClicks" : 20,
      "uniqueClicks" : 10
    } ]
  } ],
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/statistics/responses?mailingId=5&includeLinkData=true&includeTypeData=true"
    }
  }
}

Sending statistics

The sending statistics contains the most important sending information about a mailing.

Sending statistics are only available for the following mailing types (see Mailing type):

  • REGULAR_MAILING

  • ACTION_MAILING

  • TIME_TRIGGER_MAILING

  • SPLIT_TEST_MAILING

Retrieve sending statistics for a mailing

GET /statistics/sendings{?mailingId}

A GET request with an mailing ID parameter will return the requested sending statistics.

Request parameters

Parameter Required Description

mailingId

yes

The ID of the mailing.

Response structure

Path Type Description

recipientsCount

Number

Number of recipients.

deliveredMailsCount

Number

Number of successfully delivered sendings.

bounceCount

Number

Number of bounces (hard bounces, soft bounces, spam bounces and unknown bounces and rejections).

sentErrorCount

Number

Number of sending errors.

notSentMailsCount

Number

Number of not sent sendings.

mailsPerHour

Number

Sending speed as sent mails per hour.

averageMailSize

Number

Average mail size in bytes.

startDate

String

Point in time when sending started.

endDate

String

Point in time when sending ended.

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/statistics/sendings?mailingId=1' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 405

{
  "startDate" : "1970-01-18T18:18:43Z",
  "endDate" : "1970-01-18T18:19:04Z",
  "mailsPerHour" : 319166.667,
  "recipientsCount" : 2100,
  "deliveredMailsCount" : 2000,
  "sentErrorCount" : 10,
  "bounceCount" : 5,
  "notSentMailsCount" : 85,
  "averageMailSize" : 654.3,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/statistics/sendings?mailingId=1"
    }
  }
}

Text modules

Text modules are a kind of reusable content, that can be used in mailings. Content that appears in many mailings, for example an imprint part, can be written once and then used by simply referencing it by name in a mailing. Text modules can either be global, which means they are accesible in all mailing lists and therefore in all mailings, or they can be created list specific.

Retrieve single text module

GET /text-modules/{id}

A GET request with an ID parameter will return the requested text module.

Request structure

Table 52. /customer/rest/v1/text-modules/{id}
Parameter Description

id

The ID of the text module

Embeddable relations

Relation Description

inx:editor-content

The text and html content of the text module

inx:dynamic-parameters

The dynamic parameter used in the requested text module

inx:recipient-attributes

The recipient attributes used in the requested text module

Response structure

Path Type Description

id

Number

The ID of the text module

name

String

The name of the text module

listId

Number

The listId of the text module

modificationDate

Null

the timestamp when the text module was last updated

creationDate

Null

the timestamp when the text module was created

type

String

The content format type of the module. Possible Types: [HTML, TEXT, TEXT_HTML]

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/text-modules/1' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 487

{
  "name" : "textmodule1",
  "id" : 1,
  "type" : "TEXT",
  "listId" : 12,
  "creationDate" : null,
  "modificationDate" : null,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/text-modules/1"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/12"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve textmodule collection

GET /text-modules{?listId,embedded}

A GET request on the text module resource will return the first page of text modules.

Request parameters

Parameter Required Description

listId

no

The ID of the list to retrieve text modules for. To receive the global text modules use listId=1.

lastModifiedSince

no

The date filter for last modified date.

embedded

no

Indicates the relations of the resources that should be embedded in the result.

'If-modified-since' HTTP Header

The header makes request conditional

  • if header not set, returns status code 200 and body with existing text-modules. See section Response Structure.

  • if header set and text-modules has not been modified since date, the response is a 304(not modified) without any body.

  • if header set, but text-modules has no modification date at all, the response is a 304(not modified) without any body.

  • if header set and something has changed, returns status code 200 and body with existing text-modules. See section Response Structure.

  • "Wed, 21 Oct 2015 07:28:00 GMT" date format is supported

  • ISO date format is supported (2020-08-25T12:25:34Z)

Request structure

GET /customer/rest/v1/text-modules?listId=15&embedded=inx:dynamic-parameters HTTP/1.1
If-modified-since: Wed, 21 Feb 2024 07:28:00 GMT
Host: api.inxmail.com

Embeddable relations

Relation Description

inx:dynamic-parameters

The dynamic parameters used in the requested text module

Response structure

See section pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/text-modules?listId=15&embedded=inx:dynamic-parameters' -i -X GET \
    -H 'If-modified-since: Wed, 21 Feb 2024 07:28:00 GMT'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1804

{
  "_embedded" : {
    "inx:text-modules" : [ {
      "name" : "Name of the mailing",
      "id" : 1,
      "type" : "TEXT_HTML",
      "listId" : 15,
      "creationDate" : null,
      "modificationDate" : null,
      "_embedded" : {
        "inx:dynamic-parameters" : {
          "text" : null,
          "html" : null,
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/text-modules/1/dynamic-parameters"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/text-modules/1"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/15"
        }
      }
    }, {
      "name" : "Name of the mailing",
      "id" : 2,
      "type" : "TEXT_HTML",
      "listId" : 15,
      "creationDate" : null,
      "modificationDate" : null,
      "_embedded" : {
        "inx:dynamic-parameters" : {
          "text" : null,
          "html" : null,
          "_links" : {
            "self" : {
              "href" : "https://api.inxmail.com/customer/rest/v1/text-modules/2/dynamic-parameters"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/text-modules/2"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/15"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/text-modules?afterId=0&pageSize=4&listId=15&embedded=inx%3Adynamic-parameters"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Create new text module for existing list

POST /text-modules

A POST request with a request JSON body as below will create a new text module for a specific list.

Payload Structure

{
  "name" : "textmoduleTest",
  "listId" : 12,
  "type" : "TEXT",
  "text" : "This is the Text",
  "html" : "<p>Html code</p>"
}
Path Type Description Constraints

name

String

The name of the text module

Name must be unique within provided list

listId

Number

The id of the list that the text module should be created on

type

String

The content format type of the module. Possible Types: [HTML, TEXT, TEXT_HTML]

text

String

The text content of the text module. Required if type is set to TEXT or TEXT_HTML

html

String

The html content of the text module. Required if type is set to HTML or TEXT_HTML

Note: The html field will only be saved in the database if the type is HTML or TEXT_HTML. Likewise, the text field will only be saved in the database if the type is TEXT or TEXT_HTML.

Response structure

{
  "text" : "This is the Text",
  "name" : "textmoduleTest",
  "id" : 1,
  "type" : "TEXT",
  "listId" : 12,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/text-modules"
    }
  }
}
Path Type Description

id

Number

The id of the created text module

name

String

The name of the created text module

listId

Number

The id of the list that the text module belongs to

type

String

The content format type of the created module. Possible Types: [HTML, TEXT, TEXT_HTML]

text

String

The text content of the newly created text module.

html

String

The html content of the newly created text module.

_links

Object

Links to other resources

Note: The html field will only be included in the response if the type is HTML or TEXT_HTML. Likewise, the text field will only be included if the type is TEXT or TEXT_HTML.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/text-modules/' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "textmoduleTest",
  "listId" : 12,
  "type" : "TEXT",
  "text" : "This is the Text",
  "html" : "<p>Html code</p>"
}'
Response
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/text-modules
Content-Type: application/hal+json
Content-Length: 222

{
  "text" : "This is the Text",
  "name" : "textmoduleTest",
  "id" : 1,
  "type" : "TEXT",
  "listId" : 12,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/text-modules"
    }
  }
}

Update an existing text module

PUT /text-modules/{id}

A PUT request with a request JSON body as below will update the text module with the given id.

Request Structure

Table 53. /customer/rest/v1/text-modules/{id}
Parameter Description

id

The ID of the text module

Payload Structure

Updatable fields:

{
  "name" : "New textmodule Name",
  "text" : "This is the new Text",
  "html" : "<p>New Html code (will be discarded)</p>"
}
Path Type Description Constraints

name

String

The new name of the text module

The new name must be unique within provided list

text

String

The new text content of the text module. Required if type of the text module is TEXT or TEXT_HTML

html

String

The new html content of the text module. Required if type of the text module is HTML or TEXT_HTML

Note: The html field will only be saved in the database if the type is HTML or TEXT_HTML. Likewise, the text field will only be saved in the database if the type is TEXT or TEXT_HTML.

Response structure

{
  "name" : "New textmodule Name",
  "id" : 1,
  "type" : "TEXT",
  "listId" : 12,
  "creationDate" : null,
  "modificationDate" : null,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/text-modules"
    }
  }
}
Path Type Description

id

Number

The id of the updated text module

name

String

The name of the updated text module

listId

Number

The id of the list that the text module belongs to

type

String

The content format type of the updated module. Possible Types: [HTML, TEXT, TEXT_HTML]

modificationDate

Null

the timestamp when the text module was last updated

creationDate

Null

the timestamp when the text module was created

_links

Object

Links to other resources

Note: The html field will only be included in the response if the type is HTML or TEXT_HTML. Likewise, the text field will only be included if the type is TEXT or TEXT_HTML.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/text-modules/1' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "New textmodule Name",
  "text" : "This is the new Text",
  "html" : "<p>New Html code (will be discarded)</p>"
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 250

{
  "name" : "New textmodule Name",
  "id" : 1,
  "type" : "TEXT",
  "listId" : 12,
  "creationDate" : null,
  "modificationDate" : null,
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/text-modules"
    }
  }
}

Deleting an existing text module

DELETE /text-modules/{id}

A DELETE request with an id url parameter will delete the text module with that id.

Request Structure

Table 54. /customer/rest/v1/text-modules/{id}
Parameter Description

id

The ID of the text module

Example

Curl request
$ curl 'https://api.inxmail.com/customer/rest/v1/text-modules/1' -i -X DELETE \
    -H 'Content-Type: application/json'
HTTP request
DELETE /customer/rest/v1/text-modules/1 HTTP/1.1
Content-Type: application/json
Host: api.inxmail.com
Response
HTTP/1.1 204 No Content

Retrieve recipient attributes used in text module

GET /text-modules/{id}/recipient-attributes

A GET request with an ID parameter will return the recipient attributes that are used within the requested text module.

Request path parameters

Table 55. /customer/rest/v1/text-modules/{id}/recipient-attributes
Parameter Description

id

The ID of the text module

Response structure

{
  "htmlRecipientAttributes" : [ {
    "name" : "IntegerAttribute",
    "type" : "INTEGER",
    "id" : 3,
    "maxTextLength" : null
  }, {
    "name" : "DoubleAttribute",
    "type" : "DOUBLE",
    "id" : 7,
    "maxTextLength" : null
  }, {
    "name" : "DateTimeAttribute",
    "type" : "DATETIME",
    "id" : 8,
    "maxTextLength" : null
  }, {
    "name" : "BooleanAttribute",
    "type" : "BOOLEAN",
    "id" : 2,
    "maxTextLength" : null
  } ],
  "textRecipientAttributes" : [ {
    "name" : "emailAttribute",
    "type" : "EMAIL",
    "id" : 5,
    "maxTextLength" : null
  }, {
    "name" : "TimeAttribute",
    "type" : "TIME",
    "id" : 6,
    "maxTextLength" : null
  }, {
    "name" : "DateAttribute",
    "type" : "DATE",
    "id" : 4,
    "maxTextLength" : null
  }, {
    "name" : "TextAttribute",
    "type" : "TEXT",
    "id" : 1,
    "maxTextLength" : 80
  } ],
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/text-modules/1/recipient-attributes"
    }
  }
}
Path Type Description

textRecipientAttributes

Array

Array containing all used recipient attributes in the Text content.

textRecipientAttributes[].name

String

The name of the recipient attribute

textRecipientAttributes[].id

Number

The id of the recipient attribute

textRecipientAttributes[].type

String

The data type of the recipient attribute. Possible data Types: [INTEGER, DOUBLE, BOOLEAN, DATE, TIME, DATETIME, TEXT]

textRecipientAttributes[].maxTextLength

Number

The maximum text length of the attribute (if type is TEXT)

htmlRecipientAttributes

Array

Array containing all used recipient attributes in the HTML content.

htmlRecipientAttributes[].name

String

See description of textRecipientAttributes.name

htmlRecipientAttributes[].id

Number

See description of textRecipientAttributes.id

htmlRecipientAttributes[].type

String

See description of textRecipientAttributes.type

htmlRecipientAttributes[].maxTextLength

Number

See description of textRecipientAttributes

_links

Object

Links to other resources

Note:

  • The fields textRecipientAttributes and htmlRecipientAttributes are only included depending on the content type of the text module. Otherwise, they are NULL.

  • The attribute field maxTextLength will only be included if the type of the recipient attribute is TEXT.

  • The "email" attribute of a recipient is a special case and will only include the name of the attribute. See example below.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/text-modules/1/recipient-attributes' -i -X GET \
    -H 'Content-Type: application/json'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1021

{
  "htmlRecipientAttributes" : [ {
    "name" : "IntegerAttribute",
    "type" : "INTEGER",
    "id" : 3,
    "maxTextLength" : null
  }, {
    "name" : "DoubleAttribute",
    "type" : "DOUBLE",
    "id" : 7,
    "maxTextLength" : null
  }, {
    "name" : "DateTimeAttribute",
    "type" : "DATETIME",
    "id" : 8,
    "maxTextLength" : null
  }, {
    "name" : "BooleanAttribute",
    "type" : "BOOLEAN",
    "id" : 2,
    "maxTextLength" : null
  } ],
  "textRecipientAttributes" : [ {
    "name" : "emailAttribute",
    "type" : "EMAIL",
    "id" : 5,
    "maxTextLength" : null
  }, {
    "name" : "TimeAttribute",
    "type" : "TIME",
    "id" : 6,
    "maxTextLength" : null
  }, {
    "name" : "DateAttribute",
    "type" : "DATE",
    "id" : 4,
    "maxTextLength" : null
  }, {
    "name" : "TextAttribute",
    "type" : "TEXT",
    "id" : 1,
    "maxTextLength" : 80
  } ],
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/text-modules/1/recipient-attributes"
    }
  }
}

Test mail groups

A test mail group represents a set of email-addresses, that can be used to send test emails.

Retrieve single test mail group

GET /test-mail-groups/{id}

A GET request with an ID parameter will return the requested test mail group.

Request structure

Table 56. /customer/rest/v1/test-mail-groups/{id}
Parameter Description

id

The ID of the test profile

Response structure

Path Type Description

id

Number

The ID of the test mail group

name

String

The name of the test mail group

listId

Number

The ID of the list holding the test mail group.

emails

Array

The email addresses of the test mail group

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/test-mail-groups/1' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 472

{
  "name" : "name",
  "id" : 1,
  "listId" : 12,
  "emails" : [ "test1@test.invalid", "test2@test.invalid" ],
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/test-mail-groups/1"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/12"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve test mail group collection

GET /test-mail-groups

A GET request on the test mail group resource will return the first page of the test mail group.

Request parameters

There are no request parameters available at the moment.

Response structure

See section pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/test-mail-groups' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1908

{
  "_embedded" : {
    "inx:test-mail-groups" : [ {
      "name" : "test mail group 1 name",
      "id" : 1,
      "listId" : 3,
      "emails" : [ "test1@test.invalid", "test2@test.invalid" ],
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/test-mail-groups/1"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        }
      }
    }, {
      "name" : "test mail group 2 name",
      "id" : 2,
      "listId" : 3,
      "emails" : [ "test2a@test.invalid", "test2b@test.invalid" ],
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/test-mail-groups/2"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        }
      }
    }, {
      "name" : "test mail group 3 name",
      "id" : 3,
      "listId" : 3,
      "emails" : [ "test3a@test.invalid", "test3b@test.invalid" ],
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/test-mail-groups/3"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        }
      }
    }, {
      "name" : "test mail group 4 name",
      "id" : 4,
      "listId" : 3,
      "emails" : [ "test4a@test.invalid", "test4b@test.invalid" ],
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/test-mail-groups/4"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/3"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/test-mail-groups?pageSize=4"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Test Sendings

Test Sendings can be created to send the content of a mailing by email to a specified group of recipients.

Create a test sending

POST /test-sendings

A POST request with the following request body creates a test sending.

Request structure

POST /customer/rest/v1/test-sendings/ HTTP/1.1
Content-Type: application/hal+json
Content-Length: 98
Host: api.inxmail.com

{
  "mailingId" : 1,
  "testMailGroupId" : 2,
  "recipientIds" : [ 3 ],
  "testProfileIds" : [ ]
}

A successful response has the http return code 202 (accepted).

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/test-sendings/' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "mailingId" : 1,
  "testMailGroupId" : 2,
  "recipientIds" : [ 3 ],
  "testProfileIds" : [ ]
}'
Response
HTTP/1.1 202 Accepted

Preview

The preview can be used to generate a personalized preview of a text or html mailing body. The preview ist constructed without the existence of a complete mailing. Only a text or html body is needed to create the preview.

Create a preview

POST /temporary-preview

A POST request with the following request body creates a preview.

Request structure

POST /customer/rest/v1/temporary-preview/ HTTP/1.1
Content-Type: application/hal+json
Content-Length: 130
Host: api.inxmail.com

{
  "listId" : 200,
  "recipientId" : 1,
  "html" : "html",
  "subject" : "subject",
  "text" : "text",
  "testProfileId" : null
}

These fields can be used:

Path Type Description Constraints

listId

Number

The ID of the list

  • Must not be null

recipientId

Number

The id of the recipient is used for personalization. The field cannot be set, if the parameter testProfileId is used. If neither recipientId nor testProfileId is set, a dummy recipient with the email address unknown@unknown.invalid is used.

testProfileId

Null

The test profile id is used for personalization. The field cannot be set, if the parameter recipientId is used. If neither recipientId nor testProfileId is set, a dummy recipient with the email address unknown@unknown.invalid is used.

html

String

The HTML part of the preview

text

String

The text part of the preview

subject

String

The subject of the mailing

  • Must not be null

A successful response has the http return code 200 (OK).

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/temporary-preview/' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -d '{
  "listId" : 200,
  "recipientId" : 1,
  "html" : "html",
  "subject" : "subject",
  "text" : "text",
  "testProfileId" : null
}'
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 130

{
  "recipientId" : 1,
  "testProfileId" : null,
  "subject" : "subject",
  "listId" : 200,
  "html" : "html",
  "text" : "text"
}

Design collection

A design collection represents a single template library for a mailing.

Retrieve single design collection

GET /design-collections/5

A GET request with a ID parameter will return the requested design collection.

Request structure

GET /customer/rest/v1/design-collections/5 HTTP/1.1
Host: api.inxmail.com

Response structure

Path Type Description

name

String

The name of the design collection

displayName

String

The display name of the design collection

version

String

The version string of the design collection

listId

Number

The associated listId of the design collection

id

Number

The ID of the design collection

lastSaveDate

String

The last saved date of the design collection

_links

Object

Links to other resources

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/design-collections/5' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 513

{
  "id" : 5,
  "listId" : 1,
  "name" : "name",
  "displayName" : "displayName",
  "version" : "20220101",
  "lastSaveDate" : "2024-11-19T08:47:21Z",
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/design-collections/5"
    },
    "inx:list" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/lists/1"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Retrieve list of design collections

GET /design-collections

A GET request on the design collection resource will return the first page of the design collection.

Request parameters

There are no request parameters available at the moment.

Response structure

See section pagination.

Example

Request
$ curl 'https://api.inxmail.com/customer/rest/v1/design-collections' -i -X GET
Response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1285

{
  "_embedded" : {
    "inx:designcollections" : [ {
      "displayName" : "displayName1",
      "version" : "20220101",
      "name" : "name1",
      "id" : 1,
      "listId" : 1,
      "lastSaveDate" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/design-collections/1"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/1"
        }
      }
    }, {
      "displayName" : "displayName2",
      "version" : "20220101",
      "name" : "name2",
      "id" : 2,
      "listId" : 1,
      "lastSaveDate" : null,
      "_links" : {
        "self" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/design-collections/2"
        },
        "inx:list" : {
          "href" : "https://api.inxmail.com/customer/rest/v1/lists/1"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/design-collections?afterId=0&pageSize=2"
    },
    "next" : {
      "href" : "https://api.inxmail.com/customer/rest/v1/design-collections?afterId=2&pageSize=2"
    },
    "curies" : [ {
      "href" : "https://apidocs.inxmail.com/xpro/rest/v1/relations/{rel}",
      "name" : "inx",
      "templated" : true
    } ]
  }
}

Legal Information

Legal Notice Data Privacy