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.66
-
New: DELETE endpoint for blacklist-entries by ID. See Blacklist entries
-
New: PUT endpoint for blacklist-entries. See Blacklist entries
-
New: Preview for blacklist-entries. See Blacklist entries
-
New: Filter parameter patternContainsIgnoreCase for collection blacklist-entries. See Blacklist entries
-
New: POST endpoint for subscription-mailings endpoint. See Subscription Mailings
-
New: Added subscriptionMailingType to subscription-mailings endpoint. See Subscription Mailings
-
New: Include clicks by type in response statistics. See Response statistics
Version 4.8.65
-
New: DELETE Test Profile. See Delete a test profile
Version 4.8.64
-
New: Get Recipient count of a mailing list improvement. See Mailing lists
-
New: GET collection of import executions. See Recipient Import
-
New: Advanced Imports. See Advanced Recipient Import
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
-
New: Get all Links of a mailing with clicks. See Response statistics
Version 4.8.61
-
New: Get all lists for single Recipient. See Recipients
-
New: Create Action Mailing. See Action-Mailings
-
New: Update ActionTrigger with actions sequence items. See Action Triggers
-
New: Create ActionTrigger with actions sequence items. See Action Triggers
-
New: Additional parameter to include reaction data in sending-protocol. See Sending Protocol
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
-
New: Filter recipient collection by unavailable flag. See Retrieve recipients collection
-
New: Filter lists by ids. See Mailing lists
-
New: Get attributes sorted by ids. See Recipient Attributes
-
New: Delete a recipient from an unsubscribed tab with "deleteUnsubscribed" parameter See Recipients
Version 4.8.57
-
New: GET recipients by target group id. See Retrieve recipients collection
-
New: Add If-Modified-Since header to attribute request See Recipient Attributes
-
New: Add If-Modified-Since header to target-group request See Target groups
-
New: Add If-Modified-Since header to text-modules request See Text modules
-
New: Add modificationDate field to body of get lists response See Mailing lists
-
New: Add Filter lists by name Mailing lists
-
New: Get clicks by listIds for Mailings, Split test mailings, Trigger mailings See Clicks
Version 4.8.55
-
New: Endpoint for un-subscription settings of a list. See Unsubscription Settings
-
New: PUT subscription settings See Subscription Settings
-
New: PUT unsubscription settings See Unsubscription Settings
-
New: DELETE recipient attributes - See Delete a recipient attribute
Version 4.8.54
-
New: Endpoint for subscription Settings of a list. See Subscription Settings
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
-
New: Retrieve a list setting value.See Retrieving a list setting
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
-
New: Create new endpoint for creation of a new text module for a given list. See Text modules
-
New: Create new endpoint for calculation of mailing size. See Calculate size of rendered mailing content
-
New: Create a new http datasource. See HTTP Datasources
-
New: Update a http datasource. See HTTP Datasources
Version 4.8.46
-
New: Retrieve a single http datasource. See HTTP Datasources
-
New: Retrieve a collection of http datasources. See Retrieve HTTP datasource collection
-
New: Delete a single http datasource. See Delete HTTP datasource
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
-
New: Revoke an already granted mailing approval. See Mailing Approvals
-
New: Fetched recipients now contain a normalized email address. See Recipients
-
New: Delete a specified recipient from a specified list. See Delete recipient from list
Version 4.8.41
-
New: Delete target group. See Delete existing target group
Version 4.8.40
-
New: Retrieve action triggers. See Action Triggers
-
New: It is now possible to create a mailing with editorContentType is of some xml type. See Copy regular mailing with XML content
Version 4.8.39
-
New: It is now possible to get the editor content for regular mailings where the editorContentType is of some xml type. See Retrieve editor content of a regular mailing
Version 4.8.38
-
New: Retrieve design collections. See Design collection
Version 4.8.36
-
New: Send a single RegularMailing to a specified recipient. See [send-a-mailing-continue-sending-of-an-interrupted-sending]
Version 4.8.35
-
New: Retrieve the format type of a text module. See Text modules
-
Fixed: Scheduling a RegularMailing caused targetGroup information to be lost. See Schedule a regular mailing
Version 4.8.32
-
New: Added endpoint for creating target groups. See Create a target group
-
New: Added filterString to target groups. See The target group condition
-
new: Delete a regular mailing. See Delete a regular mailing
Version 4.8.31
-
New: Patch target group configuration for regular mailings. See Update a regular mailing
Version 4.8.30
-
New: Retrieve trackingPermissionEvents for multiple listids. See Retrieve tracking permission event collection
-
New: Filter trackingPermissionEvents per type of event. See Tracking Permission events
-
New: Added eventOriginatorTypes field to tracking permission event controller. See Tracking Permission events
Version 4.8.29
-
New: Retrieve target group configuration for Regular Mailings. See Regular Mailings
-
New: Retrieve global recipient count. See Retrieve recipient count of a mailing list
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
-
New: Added functionality for searching mailings by state. See Retrieve regular mailing collection
-
New: Added parameter "suppliedRemoteAddress" for tracking permission request IP addresses. See Create tracking permission
-
New: Added parameter "suppliedRemoteAddress" for subscription request IP addresses. See Subscribing a recipient to a list
-
New: Added parameter "suppliedRemoteAddress" for unsubscription request IP addresses. See Unsubscribing a recipient from a list
Version 4.8.26
-
New: Query the sending details of a sending. See Retrieve sending details of a specific sending
Version 4.8.25
-
New: Reschedule a regular mailing. See Reschedule a regular mailing
-
New: Unschedule a regular mailing. See Unschedule a regular mailing
-
New: Create a mailing preview of a text or html mailing body part. See Preview
-
New: The subscription source can be set when subscribing a recipient to a list. See Subscribing a recipient to a list
-
New: The subscription source can be set when unsubscribing a recipient from a list. See Unsubscribing a recipient from a list
-
New: Retrieve a regular mailing collection sent before a specific date. See Retrieve regular mailing collection
Version 4.8.24
-
New: Update a testprofile. See Update a test profile
-
New: Create a testprofile. See Create a test profile
-
New: List collection query has new parameters createdAfter and createdBefore. See Mailing lists
-
New: Schedule a regular mailing. See Regular Mailings
-
New: Grant instant approval of a mailing. See Mailing Approvals
-
New: Added a flag to include all user attributes when retrieving test profiles. See Test profiles
Version 4.8.23
-
New: Retrieve the number of subscribed recipients of a mailing list. See Retrieve recipient count of a mailing list
-
New: Send a personalised mailing as a test sending to a test mail group. See Test Sendings
-
New: Retrieve a specific approval, or the collection of approvals for a given mailing. See Mailing Approvals
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
-
Changed: The MANUAL_SUBSCRIPTION description has been updated. See Recipient subscriptions
-
Changed: The MANUAL_UNSUBSCRIPTION description has been updated. See Recipient unsubscriptions
Version 4.8.18
-
New: Query subscription and unsubscription event collection by param 'listIds'. See: Recipient subscriptions
Version 4.8.17
-
New: Embed editor content into regular mailing. See: Embeddable relations
-
New: Update a regular mailing. See: Update a regular mailing
-
New: Create a regular mailing. See: Create regular mailing
-
New: Retrieve editor content of a regular mailing. See: Regular Mailings
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
-
New: Retrieve a specific regular mailing or the regular mailings collection. See: Regular Mailings
-
New: Retrieve the rendered content of a specific regular mailing. See: Regular Mailings
-
New: Retrieve links of a specific regular mailing. See: Regular Mailings
-
New: Added filters for sending collection. Sendings can be filtered by mailing and list ids. See: Retrieve all sendings of all specified mailings
-
New: Retrieve all links by the ids of the corresponding mailings or by the types of the links. See: Retrieve link collection
Version 4.8.14
-
New: Added filter for web-beacon-hits. Retrieve web-beacon-hits by the ids of the corresponding mailings or lists. See: Retrieve web beacon hits collection
-
New: Retrieve sendings where the sending finished before or after a specific date. See: Retrieve all sendings of all specified mailings
-
New: Retrieve the sending protocol, including embedded recipients and recipient attributes. See: Sending Protocol
-
New: Retrieve link collection. See: Retrieve link collection
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
-
Changed: Retrieve bounces with embedded recipients and recipient attributes. See: Retrieve bounce collection
-
Changed: Retrieving an unsubscription event now will also return the id of the mailing and the id of the sending associated to this event. See: Retrieving an unsubscription event
Version 4.8.7
-
New: Retrieve all recipients, which are unsubscribed from a specified list. See Retrieve recipients collection
-
New: Retrieve subscription dates for specific lists when selecting recipients.. See Retrieve recipients collection
-
Changed: Retrieving a recipient now will also return the bounce status of the recipient. See: Recipients
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
-
New: Retrieve test profiles by their type. See: Test profiles
-
New: Retrieve all blacklist entries or just a single blacklist entry. See: Blacklist entries
-
New: Remove blacklist entries. See: Blacklist entries
-
New: Create a new blacklist entry. See: Blacklist entries
-
New: Retrieve links by id. See: Mailing links
-
New: Get response statistics for a mailing. See: Response statistics
-
New: Get sending statistics for a mailing. See: Sending statistics
Version 4.8.0
-
New: Address a recipient by their email in a PATCH request. See: Patching a recipient
-
New: Retrieve tracking permission events for a given recipient email address. See Retrieve tracking permission event collection
-
New: It is possible to overwrite the default import conflict mode for updating recipient attributes. See: Recipient Import
-
New: Retrieve test profiles from a given list. See: Test profiles
-
New: Retrieve sendings by id. See: Sendings
-
New: Address tracking permissions by the email address of a recipient. See: Tracking permissions
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
-
New: Retrieve tracking permission events with optional embedded recipients. See: Retrieve tracking permission event collection
-
New: Retrieve subscription events with optional embedded recipients. See: Retrieve subscription event collection
-
New: Retrieve unsubscription events with optional embedded recipients. See: Retrieve unsubscription events collection
-
New: Delete all subscribed recipients from a given list. See: Memberships
-
New: Delete only subscribed recipients with a given user attribute and its value from a given list. See: Memberships
-
New: Retrieve clicks and web beacon hits within a given period of time. See: Retrieve click collection and Retrieve web beacon hits collection
-
New: Retrieve only clicks and web beacon hits of recipients with granted tracking permissions. See: Retrieve click collection and Retrieve web beacon hits collection
-
New: Retrieve recipients with a given user attribute and value. See: Retrieve recipients collection
Version 4.7.2:
-
New: Retrieve bounces for a given mailing within a given start and end date. See: Retrieve bounce collection
-
New: Retrieve clicks for a given mailing with optional embedded recipients. See: Retrieve click collection
-
New: Retrieve web beacon hits for a given mailing with optional embedded recipients. See: Retrieve web beacon hits collection
-
New: Retrieve tracking permission event with optional embedded recipients. See: Retrieve tracking permission event collection
-
New: Retrieve links for a given mailing and filter them by their link types. See: Mailing links
-
New: A mailing now includes links to the corresponding links, clicks and web beacon hits. See: Mailings
-
Changed: Default page size for collections has been increased from 100 to 1000. See: Limiting result size
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
orprevious
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.
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.
Guaranteed functionality | Possible changes in functionality |
---|---|
|
|
Guaranteed functionality | Possible changes in functionality |
---|---|
|
|
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 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 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 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 forPATCH
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 withmultipart/form-data
as the common choice andmultipart/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 |
|
|
Date only |
|
|
Time only |
|
|
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.
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 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
.
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, 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 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:
-
The DST offset of the time zone observed by the client application entering the value
-
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:
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.
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).
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.
HTTP Response Status Code | Description |
---|---|
200 OK |
|
201 Created |
|
202 Accepted |
|
204 No Content |
HTTP Response Status Code | Description |
---|---|
400 Bad Request |
This is a typical Wide ranging error class. |
401 Unauthorized |
|
403 Forbidden |
|
404 Not Found |
|
405 Method Not Allowed |
|
406 Not Acceptable |
See also supported Media types. |
409 Conflict |
|
413 Payload Too Large |
|
415 Unsupported Media Type |
See also supported Media types. |
429 Too many requests |
HTTP Response Status Code | Description |
---|---|
500 Internal Server Error |
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 |
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:
-
Due to a client error
-
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:
-
Failing to provide credentials for authentication
-
Providing incorrect credentials for authentication
-
Accessing a non existent resource
-
Using malformed path or query parameters
-
Submitting a malformed JSON document
-
Submitting a JSON document using incorrect data types
-
Submitting a JSON document with validation errors
-
Manipulating a locked resource
-
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:
-
Well defined error conditions, e.g.
404 Not Found
-
Wide ranging error classes, e.g.
400 Bad Request
-
Validation errors
-
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
duplicate-resource
409 Conflict
Indicates that a resource with the given name or other identifier already exists. This might be the case if:
-
you tried POSTing a resource with a name or identifier which is already in use
-
you made a PUT request to rename a resource to a name which is already in use
Choose a different name which is not yet taken.
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
locked-resource
400 Bad Request
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.
Wait for the resource to be unlocked. This might involve periodic retries or, if applicable, informing the user.
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
invalid-parameter-value
400 Bad Request
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
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.
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
invalid-request-body
400 Bad Request
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.
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.
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
missing-parameter
400 Bad Request
Indicates that a mandatory request parameter is missing.
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.
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
missing-request-part
400 Bad Request
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.
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.
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
type-mismatch
400 Bad Request
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.
Check if you provided the correct type for all request parameters (i.e. query parameters). The error detail outlines which parameter caused the error.
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
unresolvable-request
400 Bad Request
Indicates that the request could not be resolved.
This is a very rare issue. If you should encounter this error, please contact us.
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
validation-error
400 Bad Request
Indicates that the request body you provided did not pass validation.
This issue can only be observed in conjunction with POST
and PUT
requests.
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.
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
duplicate-email
409 Conflict
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.
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.
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
blacklisted
400 Bad Request
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.
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.
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
ambiguous-email
409 Conflict
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.
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.
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
subscription-error
400 Bad Request
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.
Check the result
and detail
fields of the problem document for further information on the problem at hand.
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
unsubscription-error
400 Bad Request
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.
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.
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
mailing-render-error
400 Bad Request
Indicates that there were errors with the result that the mailing could not be rendered.
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.
Path | Type | Description |
---|---|---|
|
|
The list of errors leading to this occuring exception. |
|
|
The description of the error. |
|
|
The position in the source code where the error occurred. |
|
|
1001 |
|
|
string, another string |
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
unknown-recipient-attribute
400 Bad Request
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).
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.
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
unparseable-recipient-attribute
400 Bad Request
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.
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.
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
unparseable-recipient-attribute-filter
400 Bad Request
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.
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.
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
unsupported-recipient-attribute-filter
400 Bad Request
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.
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.
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
Resource collection link relation
The lists
relation indicates that the corresponding link points to a collection of mailing lists.
list
Resource link relation
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
Resource collection link relation
The mailings
relation indicates that the corresponding link points to a collection of mailings.
mailing
Resource link relation
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
Resource link relation
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
Resource link relation
The links
relation indicates that the corresponding link points to the links collection of a specific mailing.
attributes
Resource collection link relation
The attributes
relation indicates that the corresponding link points to a collection of recipient attributes.
recipients
Resource collection link relation
The recipients
relation indicates that the corresponding link points to a collection of recipients.
recipient-imports
Resource collection link relation
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
Resource collection link relation
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
Resource collection link relation
The errors
relation indicates that the corresponding link points to a collection of import file errors.
subscription-events
Resource collection link relation
The subscription-events
relation indicates that the corresponding link points to a collection of subscription events.
unsubscription-events
Resource collection link relation
The unsubscription-events
relation indicates that the corresponding link points to a collection of
unsubscription events.
sendings
Resource collection link relation
The sendings
relation indicates that the corresponding link points to a collection of sendings.
clicks
Resource collection click relation
The clicks
relation indicates that the corresponding link points to a collection of clicks.
web-beacon-hits
Resource collection link relation
The web-beacon-hits
relation indicates that the corresponding link points to a collection of web-beacon-hits.
bounces
Resource link relation
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
Resource collection link relation
The blacklist-entries
relation indicates that the corresponding link points to a collection of blacklist entries.
upcoming
Resource collection link relation
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.
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
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings/1?embedded=inx:response-statistics,inx:sending-statistics' -i -X GET
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-09-05T13:32:01Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:32:01Z",
"_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-09-05T13:32:01Z",
"endDate" : "2024-09-05T13:32:01Z",
"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 |
---|---|---|
|
no |
The largest existing item ID before the page, not to be included in the page |
|
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.
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
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.
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 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 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.
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
Parameter | Description |
---|---|
|
The ID of the list |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the list |
|
|
The name of the list |
|
|
Some text describing the list |
|
|
The email address of the sender associated to this list |
|
|
The name of the sender associated to this list |
|
|
The email address which will be present in the reply-to header of every mailing sent from this list |
|
|
The display name associated with the replyToAddress |
|
|
The type of the list. Possible values are [STANDARD, DYNAMIC, ADMIN, SYSTEM] |
|
|
The point in time when this list was created |
|
|
The point in time when this list was modified |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/lists/5' -i -X GET
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
$ 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"
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
} ]
}
}
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 |
|
type |
String |
The type of the new list |
|
senderAddress |
String |
The email address of the sender of the new list |
|
senderName |
String |
The name of the sender of the new 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 |
|
description |
String |
The description of the new list |
|
Example
$ 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"
}'
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 |
|
senderAddress |
String |
The new email address of the sender of the list |
|
senderName |
String |
The new name of the sender of the 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 |
|
description |
String |
The new description of the list |
|
Example
$ 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"
}'
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
$ curl 'https://api.inxmail.com/customer/rest/v1/lists/5' -i -X DELETE
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
Parameter | Description |
---|---|
|
The ID of the list. To receive the count of all recipients use the system list with id = 1. |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the list |
|
|
The number of recipients subscribed to the list. |
|
|
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 to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/lists/5/count' -i -X GET
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 189
{
"id" : 5,
"count" : 5,
"lastCalculatedAt" : "2024-09-05T13:31:48Z",
"_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.
Note
|
As of this writing, list settings can only be written, not read. This will change with an upcoming release of this API. |
Available settings
Currently, this API supports only a limited subset of the list settings provided by Inxmail Professional. The available settings 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. |
Changing a list setting
PUT /lists/{listId}/settings/{settingName}
A PUT
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
Parameter | Description |
---|---|
|
The ID of the list to change the setting on. Must be a list of type STANDARD. |
|
The name of the setting to change. Currently only TrackingPermissionDetachedFromMembership is supported |
Payload structure
The constraints depend on the list setting to be changed. See the following table for details:
Path | Type | Description | Setting | Constraints |
---|---|---|---|---|
value |
String |
The new value of the setting |
TrackingPermissionDetachedFromMembership |
|
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/lists/5/settings/TrackingPermissionDetachedFromMembership' -i -X PUT \
-H 'Content-Type: application/hal+json' \
-d '{
"value" : "true"
}'
HTTP/1.1 200 OK
Retrieving a list setting
GET /lists/{listId}/settings/{settingName}
A GET
request with an ID parameter and a SettingName parameter payload structure will fetch the value of a
list setting.
N.b. Currently, only the setting 'TrackingPermissionDetachedFromMembership' is supported
Request structure
Parameter | Description |
---|---|
|
The ID of the list to retrieve the setting for. |
|
The name of the setting to be retrieved |
Response structure
Path | Type | Description |
---|---|---|
|
|
|
|
|
The value of the retrieved setting |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/lists/5/settings/TrackingPermissionDetachedFromMembership' -i -X GET
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 201
{
"value" : "true",
"inherited" : true,
"_links" : {
"self" : {
"href" : "https://api.inxmail.com/customer/rest/v1/lists/5/settings/TrackingPermissionDetachedFromMembership"
}
}
}
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
Parameter | Description |
---|---|
|
The ID of the list to get the subscription-settings from. |
Response structure
Path | Type | Description |
---|---|---|
|
|
The Subscription Type: 10 if confirmed opt-in, 11 if double opt-in |
|
|
if a welcome message should be send |
|
|
The id of the welcomeMailing |
|
|
The id of the time out mailing |
|
|
The id of the verification mailing |
|
|
If double opt-in timeout mailings should be send |
|
|
Number of days in which double opt-in must be confirmed |
|
|
The URL of the double opt-in landing page |
|
|
The URL of the double opt-in timeout page |
|
|
If recent mails should be send to new recipients |
|
|
If existing recipients should be overriden |
|
|
The Subscription Command |
|
|
If notifications should be send at unconfirmed subscription |
|
|
If notifications should be send at confirmed subscription |
|
|
The email address ss to send notifications to |
|
|
Links to other resources |
Example
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
$ 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"
}'
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
Parameter | Description |
---|---|
|
The ID of the list to get the unsubscription-settings from. |
Response structure
Path | Type | Description |
---|---|---|
|
|
The subscription type, 1 if confirmed opt-out, 2 if double opt-out |
|
|
The id of the mail, which should be send to confirm the unsubscription |
|
|
If a mail should be send if double opt-out is expired |
|
|
The id of the mail, which should be send if the double opt-out is expired |
|
|
The id of the goodbye message |
|
|
The duration in days, in which the double opt-out must be confirmed |
|
|
The landing page if the double opt-out is already confirmed |
|
|
The landing page if the double opt-out is expired |
|
|
If unused members should be deleted |
|
|
The preUnsubscriptionType: 0 = without, 1 = direct, 2 = jsp, 3 = external |
|
|
The landing page for the unsubscription |
|
|
The external landing page for the unsubscription |
|
|
The id of the jsp |
|
|
If notification should be for unconfirmed unsubscriptions |
|
|
If notification mails should be send when a unsubscription happens |
|
|
If a goodbye message should be send to the unsubscriber |
|
|
The command for the unsubscription |
|
|
The email address to send notifications to |
|
|
Links to other resources |
Example
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1114
{
"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,
"verificationMailingId" : 3,
"verificationTimeoutMailingId" : 3,
"notifyAddress" : "notify-me@example.com",
"_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
$ 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
}'
{
"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,
"verificationMailingId" : 3,
"verificationTimeoutMailingId" : 3,
"notifyAddress" : "notify-me@example.com",
"_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
Parameter | Description |
---|---|
|
The ID of the mailing |
Request parameters
Parameter | Required | Description |
---|---|---|
|
no |
Indicates the relations of the resources that should be embedded in the result. |
Embeddable relations
Relation | Description |
---|---|
|
Statistics regarding the sending of this mailing. Only available for mailings of type |
|
Statistics regarding the recipient responses (e.g. clicks) to this mailing. Only available for mailings of type |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the mailing |
|
|
The type of the mailing. Possible values are [REGULAR_MAILING, ACTION_MAILING, TIME_TRIGGER_MAILING, SUBSCRIPTION_TRIGGER_MAILING, SPLIT_TEST_MAILING] |
|
|
The ID of the associated list |
|
|
The name of the mailing |
|
|
The subject of the mailing |
|
|
The creation date of this mailing |
|
|
The modification date of this mailing |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings/1?embedded=inx:response-statistics,inx:sending-statistics' -i -X GET
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-09-05T13:32:01Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:32:01Z",
"_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 |
---|---|---|
|
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. |
|
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]. |
|
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. |
|
no |
If |
|
no |
If |
|
no |
If |
|
no |
Indicates the relations of the resources that should be embedded in the result. |
|
no |
All mailings that were created after this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
no |
All mailings that were created before this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
no |
All mailings that were modified after this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
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 |
---|---|
|
Statistics regarding the sending of this mailing. Only available for mailings of type |
|
Statistics regarding the recipient responses (e.g. clicks) to this mailing. Only available for mailings of type |
Response structure
See section pagination.
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings' -i -X GET
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-09-05T13:32:00Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:32:00Z",
"_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-09-05T13:32:00Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:32:00Z",
"_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-09-05T13:32:00Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:32:00Z",
"_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-09-05T13:32:00Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:32:00Z",
"_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-09-05T13:32:00Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:32:00Z",
"_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
Parameter | Description |
---|---|
|
The ID of the mailing |
Request parameters
Parameter | Required | Description |
---|---|---|
|
no |
Indicates the relations of the resources that should be embedded in the result. |
Embeddable relations
Relation | Description |
---|---|
|
The text and html content of this mailing. Only available for mailings of type |
|
Statistics regarding the sending of this mailing. Only available for mailings of type |
|
Statistics regarding the recipient responses (e.g. clicks) to this mailing. Only available for mailings of type |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the mailing |
|
|
The ID of the associated list |
|
|
The name of the mailing |
|
|
The type of the mailing. Always "REGULAR_MAILING" |
|
|
The subject of the mailing |
|
|
The state of the mailing. The state can be on of the values FINISHED, ACTIVE, DRAFT , INTERRUPTED, SCHEDULED, APPROVAL_REQUESTED or APPROVED |
|
|
The creation date of this mailing |
|
|
The modification date of this mailing |
|
|
The editor content type of the mailing. Values are TEXT; HTML; TEXT_HTML, XML_TEXT, XML_HTML and XML_TEXT_HTML |
|
|
The date a Mailing is due to be sent |
|
|
The filter configuration applied to the retrieved Mailing. Combination types are MATCH_NONE, MATCH_ONE, MATCH_ALL, FILTER_GROUP_NOT_ASSIGNED |
|
|
The IDs of the filters applied to the retrieved Mailing. |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/1?embedded=inx:response-statistics,inx:sending-statistics,inx:editor-content' -i -X GET
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-09-05T13:32:04Z",
"scheduleDate" : "2024-09-05T13:32:03Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:32:04Z",
"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 |
|
subject |
String |
The subject of the new mailing |
|
listId |
Number |
The listId of the new mailing. List must be of type |
|
editorContentType |
String |
The editor content type of the new mailing. Possible values are "TEXT", "HTML" AND "TEXT_HTML" |
|
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
$ 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"
}'
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 |
|
subject |
String |
The subject of the new mailing |
|
listId |
Number |
The listId of the new mailing. List must be of type |
|
editorContentType |
String |
The editor content type of the new mailing. Possible values are "XML_TEXT_HTML", "XML_HTML" AND "XML_TEXT" |
|
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
$ 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"
}'
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
$ 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"
}'
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
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/5' -i -X DELETE
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
Parameter | Description |
---|---|
|
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
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/1/editor-content' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/5/schedule' -i -X POST \
-H 'Content-Type: application/hal+json' \
-d '{
"scheduleDate" : "2025-09-05T13:32:05+0000"
}'
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-09-05T13:32:05Z",
"_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
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/5/schedule' -i -X PUT \
-H 'Content-Type: application/hal+json' \
-d '{
"scheduleDate" : "2025-09-05T13:32:05+0000"
}'
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 184
{
"id" : 5,
"scheduleDate" : "2025-09-05T13:32:05Z",
"_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
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/5/schedule' -i -X DELETE
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
$ curl 'https://api.inxmail.com/customer/rest/v1/regular-mailings/1/schedule' -i -X GET
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 184
{
"id" : 1,
"scheduleDate" : "2025-09-05T13:32:04Z",
"_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 |
---|---|---|
|
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. |
|
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. |
|
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]. |
|
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. |
|
no |
If |
|
no |
Indicates the relations of the resources that should be embedded in the result. |
|
no |
All mailings that were created after this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
no |
All mailings that were created before this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
no |
All mailings that were modified after this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
no |
All mailings that were modified before this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
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 |
---|---|
|
Statistics regarding the recipient responses (e.g. clicks) to this mailing. Only available for mailings of type |
|
Statistics regarding the sending of this mailing. Only available for mailings of type |
Response structure
See section pagination.
Example
$ 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
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-09-05T13:32:05Z",
"scheduleDate" : "2024-09-05T13:32:03Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:32:05Z",
"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-09-05T13:32:05Z",
"endDate" : "2024-09-05T13:32:05Z",
"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-09-05T13:32:05Z",
"scheduleDate" : "2024-09-05T13:32:03Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:32:05Z",
"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-09-05T13:32:05Z",
"endDate" : "2024-09-05T13:32:05Z",
"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-09-05T13:32:05Z",
"scheduleDate" : "2024-09-05T13:32:03Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:32:05Z",
"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-09-05T13:32:05Z",
"endDate" : "2024-09-05T13:32:05Z",
"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-09-05T13:32:05Z",
"scheduleDate" : "2024-09-05T13:32:03Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:32:05Z",
"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-09-05T13:32:05Z",
"endDate" : "2024-09-05T13:32:05Z",
"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
Parameter | Description |
---|---|
|
The ID of the mailing |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the mailing |
|
|
The ID of the associated list |
|
|
The name of the mailing |
|
|
The type of the mailing. Always "SPLIT_TEST_MAILING" |
|
|
The subject of the mailing |
|
|
The state of the mailing. The state can be on of the values FINISHED, ACTIVE, DRAFT, INTERRUPTED, SCHEDULED, APPROVAL_REQUESTED, APPROVED or ASSIGNED |
|
|
The creation date of this mailing |
|
|
The modification date of this mailing |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/split-test-mailings/1' -i -X GET
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-09-05T13:32:06Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:32:06Z",
"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 |
---|---|---|
|
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. |
|
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. |
|
no |
All mailings that were created after this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
no |
All mailings that were created before this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
no |
All mailings that were modified after this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
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
Parameter | Description |
---|---|
|
The ID of the mailing |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the mailing |
|
|
The ID of the associated list |
|
|
The name of the mailing |
|
|
The type of the mailing contains always "ACTION_MAILING" |
|
|
The subject of the mailing |
|
|
The state of the mailing. The state can be on of the values DRAFT, APPROVAL_REQUESTED, APPROVED, INACTIVE or ACTIVE |
|
|
The creation date of this mailing |
|
|
The modification date of this mailing |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/action-mailings/1' -i -X GET
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-09-05T13:31:57Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:31:57Z",
"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 |
---|---|---|
|
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. |
|
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. |
|
no |
All mailings that were created after this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
no |
All mailings that were created before this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
no |
All mailings that were modified after this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
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.66/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
Unresolved directive in mailing/structure.adoc - include::/home/jenkins/agent/workspace/est.documentation_release_4.8.66/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 of the action mailing. Valid length is [1;255] |
|
|
Subject of the action mailing. Valid length is [1;1024] |
|
|
The ID of the list associated to the action mailing. Only STANDARD lists are available for Action Mailing |
|
|
Type of the content. Next values are valid: [TEXT; HTML; TEXT_HTML]. |
|
|
Plain text content. Encoding for double quotes is required. Should not be null in case editorContentType=TEXT or TEXT_HTML. |
|
|
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 |
---|---|---|
|
|
Modification date of the action mailing. |
|
|
The mailing state of the action trigger |
|
|
The ID of the list associated to the action mailing. Only STANDARD lists are available for Action Mailing |
|
|
Subject of the action mailing. |
|
|
Creation date of the action mailing. |
|
|
Name of the action mailing. |
|
|
Id of the created action mailing. |
|
|
Type of the created action mailing. |
|
|
Links to other resources |
Example
$ 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
Parameter | Description |
---|---|
|
The ID of the mailing |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the mailing |
|
|
The ID of the associated list |
|
|
The name of the mailing |
|
|
The type of the mailing. Always "TIME_TRIGGER_MAILING" |
|
|
The subject of the mailing |
|
|
The state of the mailing. The state can be on of the values DRAFT, APPROVAL_REQUESTED, APPROVED, INACTIVE or ACTIVE |
|
|
The creation date of this mailing |
|
|
The modification date of this mailing |
|
|
Links to other resources |
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-09-05T13:32:09Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:32:09Z",
"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 |
---|---|---|
|
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. |
|
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. |
|
no |
All mailings that were created after this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
no |
All mailings that were created before this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
no |
All mailings that were modified after this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
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
Parameter | Description |
---|---|
|
The ID of the mailing |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the mailing |
|
|
The ID of the associated list |
|
|
The name of the mailing |
|
|
The type of the mailing. Always "SUBSCRIPTION_TRIGGER_MAILING" |
|
|
The subject of the mailing |
|
|
The state of the mailing. The state can be on of the values USED, DRAFT, APPROVAL_REQUESTED or APPROVED |
|
|
The creation date of this mailing |
|
|
The modification date of this mailing |
|
|
The subscrption mailing type of the mailing |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/subscription-mailings/1' -i -X GET
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-09-05T13:32:08Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:32:08Z",
"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 |
---|---|---|
|
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. |
|
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. |
|
no |
If |
|
no |
All mailings that were created after this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
no |
All mailings that were created before this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
no |
All mailings that were modified after this date (ISO 8601) will be returned. Only one value at a time can be specified. |
|
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
$ 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"
}'
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
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings/1/approvals' -i -X GET
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1542
{
"_embedded" : {
"inx:approvals" : [ {
"id" : 1,
"mailingId" : 1,
"entryDate" : "2024-09-05T13:31:55Z",
"username" : "John Smith",
"approvalComment" : "This mailing is approved.",
"approvalStateTransition" : "APPROVED",
"_links" : {
"self" : {
"href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/approvals/1"
}
}
}, {
"id" : 2,
"mailingId" : 1,
"entryDate" : "2024-09-05T13:31:55Z",
"username" : "John Smith",
"approvalComment" : "This mailing is below standard.",
"approvalStateTransition" : "INVALIDATE",
"_links" : {
"self" : {
"href" : "https://api.inxmail.com/customer/rest/v1/mailings/1/approvals/2"
}
}
}, {
"id" : 3,
"mailingId" : 1,
"entryDate" : "2024-09-05T13:31:55Z",
"username" : null,
"approvalComment" : null,
"approvalStateTransition" : "ESCALATED",
"_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
$ 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"
}'
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
$ 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"
}'
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 |
---|---|
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 |
|
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 |
|
name |
String |
Optional: The new name of the mailing’s copy. |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/operations/mailings?command=copy' -i -X POST \
-H 'Content-Type: application/hal+json' \
-d '{
"mailingId" : 2
}'
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-09-05T13:32:03Z",
"subject" : "Subject of the mailing",
"modificationDate" : "2024-09-05T13:32:03Z",
"_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
} ]
}
}
Mailing links
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
Parameter | Description |
---|---|
|
The ID of the mailing containing these links |
Request parameters
Parameter | Required | Description |
---|---|---|
|
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
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings/42/links' -i -X GET
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
Parameter | Description |
---|---|
|
The ID of the link |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the link |
|
|
The ID of the mailing containing this link |
|
|
The URL of the link |
|
|
The name of this link |
|
|
The type of this link |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/links/2' -i -X GET
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
} ]
}
}
Retrieve link collection
GET /links{?mailingIds,types}
A GET
request without any parameters will return all links.
Request parameters
Parameter | Required | Description |
---|---|---|
|
no |
The corresponding mailing ids for the desired links. More than one value can be specified with multiple query parameters or comma separated list. |
|
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
$ curl 'https://api.inxmail.com/customer/rest/v1/links?mailingIds=1,2&types=UNIQUE_COUNT,UNSUBSCRIBE_FORM,WITHDRAW_TRACKING_PERMISSION' -i -X GET
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
Parameter | Description |
---|---|
|
The ID of the mailing |
Request parameters
Parameter | Required | Description |
---|---|---|
|
no |
The ID of a specific test profile that will be used to render the mailing. |
|
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 |
---|---|---|
|
|
The rendered subject of the mailing |
|
|
The rendered text part of the mailing |
|
|
The rendered html part of the mailing |
|
|
The attachments of the mailing. Omitted if no attachments were requested with the 'includeAttachments' parameter |
|
|
The file name of the attachment |
|
|
The content type of the attachment |
|
|
The data of the attachment (base64 encoded) |
|
|
Links to other resources |
Example without attachments
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings/1/renderedContent' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/mailings/1/renderedContent?testProfileId=5&includeAttachments=true' -i -X GET
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 'https://api.inxmail.com/customer/rest/v1/mailings/1/rendered-content-size' -i -X GET
GET /customer/rest/v1/mailings/1/rendered-content-size HTTP/1.1
Host: api.inxmail.com
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:
Parameter | Description |
---|---|
|
The ID of the http datasource |
Response structure
Path | Type | Description |
---|---|---|
|
|
The name of the http datasource. |
|
|
The ID of the http data source. PDF and FILE datasources cannot be requested. |
|
|
The default value is UTF-8. |
|
|
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". |
|
|
The name of the file attachment that will be assigned if the option "attach as file attachment" was selected. |
|
|
The value is true when the encode url placeholders were selected. |
|
|
The value is true when inxmail tags were selected. |
|
|
The date of the last saving. |
|
|
The url of the http datasource. |
|
|
The use type specifies how the http datasource is used in emails. |
|
|
Links to other resources |
Example without attributes
$ curl 'https://api.inxmail.com/customer/rest/v1/datasources/http/1' -i -X GET
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 446
{
"name" : "Sample DataSource",
"id" : 1,
"contentEncoding" : null,
"url" : "www.sample.de",
"fetchStrategy" : "ONCE",
"attachmentFileName" : "SampleAttachmentFileName",
"encodeUrlPlaceholders" : true,
"useType" : "ATTACHMENT_FILE",
"lastSaveDate" : "1970-01-17T16:01:15Z",
"contentWithInxmailTags" : false,
"_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
$ curl 'https://api.inxmail.com/customer/rest/v1/datasources/http' -i -X GET
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1721
{
"_embedded" : {
"inx:datasources" : [ {
"name" : "Sample Datasource_201",
"id" : 201,
"contentEncoding" : null,
"url" : "www.one.de",
"fetchStrategy" : "ONCE",
"attachmentFileName" : "File-One-Name",
"encodeUrlPlaceholders" : true,
"useType" : "ATTACHMENT_FILE",
"lastSaveDate" : "1970-01-17T16:01:15Z",
"contentWithInxmailTags" : false,
"_links" : {
"self" : {
"href" : "https://api.inxmail.com/customer/rest/v1/datasources/http/201"
}
}
}, {
"name" : "Sample Datasource_202",
"id" : 202,
"contentEncoding" : null,
"fetchStrategy" : "RECIPIENT_CACHED",
"encodeUrlPlaceholders" : false,
"useType" : "TRANSFORMED_TEXT",
"lastSaveDate" : "1970-01-17T16:01:15Z",
"contentWithInxmailTags" : true,
"_links" : {
"self" : {
"href" : "https://api.inxmail.com/customer/rest/v1/datasources/http/202"
}
}
}, {
"name" : "Sample Datasource_203",
"id" : 203,
"contentEncoding" : null,
"fetchStrategy" : "RECIPIENT_BASED",
"encodeUrlPlaceholders" : true,
"useType" : "TEXT",
"lastSaveDate" : "1970-01-17T16:01:15Z",
"contentWithInxmailTags" : true,
"_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:
Parameter | Description |
---|---|
|
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. |
|
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,
"contentEncoding" : null,
"url" : "http://datasource.url",
"fetchStrategy" : "RECIPIENT_BASED",
"attachmentFileName" : "thisIsAnotherNewName",
"encodeUrlPlaceholders" : false,
"useType" : "ATTACHMENT_FILE",
"lastSaveDate" : null,
"contentWithInxmailTags" : false,
"_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 |
---|---|---|
|
|
The ID of the action trigger |
|
|
The name of the action trigger |
|
|
The description of the action trigger |
|
|
The ID of the list associated to the action trigger. |
|
|
The type of the action trigger |
|
|
Boolean Flag tells whether execute always or not. Used only for ON_CLICK actionTriggerType |
|
|
Collection of actionSequence items |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/actions/1' -i -X GET
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 551
{
"name" : "actionTrigger",
"id" : 1,
"description" : "This action triggers an event",
"listId" : 76,
"actionSequence" : [ ],
"actionTriggerType" : "ON_CLICK",
"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,
"actionSequence" : [ ],
"actionTriggerType" : "ON_CLICK",
"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,
"actionSequence" : [ ],
"actionTriggerType" : "ON_CLICK",
"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,
"actionSequence" : [ ],
"actionTriggerType" : "ON_CLICK",
"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,
"actionSequence" : [ ],
"actionTriggerType" : "ON_CLICK",
"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
$ curl 'https://api.inxmail.com/customer/rest/v1/actions' -i -X GET
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 2128
{
"_embedded" : {
"inx:actions" : [ {
"name" : "actor",
"id" : 1,
"description" : "acts on a thing",
"listId" : 2,
"actionSequence" : [ ],
"actionTriggerType" : "ON_CLICK",
"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,
"actionSequence" : [ ],
"actionTriggerType" : "ON_CLICK",
"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,
"actionSequence" : [ ],
"actionTriggerType" : "ON_CLICK",
"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,
"actionSequence" : [ ],
"actionTriggerType" : "ON_CLICK",
"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
$ 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 |
---|---|---|
|
|
The ID of the action trigger |
|
|
The name of the action trigger |
|
|
The description of the action trigger |
|
|
The ID of the list associated to the action trigger. |
|
|
The type of the action trigger |
|
|
Boolean Flag tells whether execute always or not. Used only for ON_CLICK actionTriggerType |
|
|
Collection of actionSequence items |
|
|
ActionSequence attributeId |
|
|
ActionSequence value |
|
|
ActionSequence actionSequenceType |
|
|
ActionSequence orderId |
|
|
ActionSequence attributeId |
|
|
ActionSequence actionSequenceType |
|
|
ActionSequence orderId |
|
|
ActionSequence value |
|
|
Links to other resources |
Example
$ 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 |
---|---|---|
|
|
The ID of the action trigger |
|
|
The name of the action trigger |
|
|
The description of the action trigger |
|
|
The ID of the list associated to the action trigger. |
|
|
The type of the action trigger |
|
|
Boolean Flag tells whether execute always or not. Used only for ON_CLICK actionTriggerType |
|
|
Collection of actionSequence items |
|
|
ActionSequence attributeId |
|
|
ActionSequence value |
|
|
ActionSequence actionSequenceType |
|
|
ActionSequence orderId |
|
|
ActionSequence attributeId |
|
|
ActionSequence actionSequenceType |
|
|
ActionSequence orderId |
|
|
ActionSequence value |
|
|
Links to other resources |
Example
$ 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.
-
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.
$ curl 'https://api.inxmail.com/customer/rest/v1/sendings/1' -i -X GET
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the sending |
|
|
The ID of the mailing |
|
|
The ID of the associated list |
|
|
The state of the sending. Possible values are [NOT_STARTED, PREPARED, SENDING, USER_INTERRUPTED, CRASHED, FINISHED] |
|
|
The start date of the sending |
|
|
The end date of the sending |
|
|
The type of the sending. Possible values are [MASS_MAILING, SINGLE_MAILING, TIME_TRIGGER_MAILING, SEQUENCE_MAILING, SPLIT_TEST_MAILING] |
|
|
The total size of the sending |
|
|
The last saved date of the sending |
|
|
Links to other resources |
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 698
{
"state" : "FINISHED",
"id" : 1,
"type" : "MASS_MAILING",
"listId" : 1,
"endDate" : "2024-09-05T13:32:15Z",
"mailingId" : 2,
"startDate" : "2024-09-05T13:32:15Z",
"lastModificationDate" : "2024-09-05T13:32:15Z",
"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-09-05T13:32:15.623Z&sendingsFinishedAfterDate=2024-09-05T13:32:15.623Z&listIds=1' -i -X GET
Request parameters
Parameter | Required | Description |
---|---|---|
|
no |
The ID of the mailing to retrieve sendings for. Only one value at a time can be specified. |
|
no |
The IDs of the lists to retrieve sendings for. |
|
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. |
|
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 |
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-09-05T13:32:15.636Z&sendingsFinishedAfterDate=2024-09-05T13:32:15.636Z' -i -X GET
Request parameters
Parameter | Required | Description |
---|---|---|
|
no |
The IDs of the mailings to retrieve sendings for. |
|
no |
The IDs of the lists to retrieve sendings for. |
|
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. |
|
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 |
---|---|---|
|
|
The ID of the sending |
|
|
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 |
|
|
The number of rejected mails (direct bounces) |
|
|
The sum of hard- and softbounces |
|
|
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). |
|
|
The number of delivered mails |
|
|
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 to other resources |
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 |
|
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)
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
}
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-09-05T13:32:14Z",
"mailingId" : 3,
"startDate" : "2024-09-05T13:32:14Z",
"lastModificationDate" : "2024-09-05T13:32:14Z",
"totalSize" : 1234,
"_links" : {
"self" : {
"href" : "https://api.inxmail.com/customer/rest/v1/sendings/1"
}
}
}
Example (mass mailing)
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
}
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-09-05T13:32:14Z",
"mailingId" : 3,
"startDate" : "2024-09-05T13:32:14Z",
"lastModificationDate" : "2024-09-05T13:32:14Z",
"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.
-
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:
Parameter | Description |
---|---|
|
The Id of the sending |
Request Parameters
Parameter | Required | Description |
---|---|---|
|
no |
Indicates the relations of the resources that should be embedded in the result. |
|
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. |
|
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 |
---|---|
|
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
$ curl 'https://api.inxmail.com/customer/rest/v1/sendings/1/protocol?embedded=inx:recipient&recipientAttributes=firstName,lastName' -i -X GET
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
Parameter | Description |
---|---|
|
The ID of the resource |
Response structure for non-text attributes
Path | Type | Description |
---|---|---|
|
|
The ID of the resource |
|
|
The name of the attribute. |
|
|
The type of the attribute. Possible values: [DATE_AND_TIME, DATE_ONLY, TIME_ONLY, INTEGER, FLOATING_POINT_NUMBER, BOOLEAN] |
|
|
The timestamp the attribute was created |
|
|
The timestamp the attribute was last updated |
|
|
Links to other resources |
Response structure for text attributes
Path | Type | Description |
---|---|---|
|
|
The ID of the resource |
|
|
The name of the attribute. |
|
|
The type of the attribute. Will be 'TEXT' in this particular case. |
|
|
The maximum length of the attribute value. Only applies to TEXT attributes. |
|
|
The timestamp the attribute was created |
|
|
The timestamp the attribute was last updated |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/attributes/5' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/attributes' -i -X GET
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 |
---|---|---|
|
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. |
Payload structure
Path | Type | Description | Constraints |
---|---|---|---|
name |
String |
The name of the new attribute |
|
type |
String |
The data type of the new attribute |
|
maxLength |
Number |
The mandatory maximum length of an attribute with type TEXT. Do not provide for attributes with other data types. |
|
Example
$ 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
}'
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
Parameter | Description |
---|---|
|
The ID of the recipient-attribute. |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/attributes/26' -i -X DELETE
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:
Parameter | Description |
---|---|
|
The ID of the resource |
Request parameters
Parameter | Required | Description |
---|---|---|
|
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 |
|
no |
If |
|
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 |
|
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 |
|
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 |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the resource |
|
|
The email address of the recipient. |
|
|
The normalized (lower case) email address of the recipient. |
|
|
Indicates the date on which a recipient was updated for the last time. The date is presented in ISO 8601 format. |
|
|
The bounce status of the recipient. If there are three or more hard bounces, the recipient is marked as unavailable. If |
|
|
The attributes of the recipient. Omitted if no attributes were requested or the recipient has no values for the requested attributes. |
|
|
The tracking permissions of the recipient. Omitted if the trackingPermissionsForLists parameter is not included in the request. |
|
|
The subscription dates of the recipient. Omitted if the subscriptionDatesForLists parameter is not included in the request. |
|
|
The unsubscription date of the recipient. Omitted if the unsubscriptionDatesForLists parameter is not included in the request. |
|
|
Links to other resources |
Example without attributes
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5?attributes=givenName&attributes=familyName' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5?allAttributes=true' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5?trackingPermissionsForLists=8,15,17' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5?subscriptionDatesForLists=8,15,17' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5?unsubscriptionDatesForLists=8,15,17' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5?completeRecipientInformation=true' -i -X GET
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 |
---|---|---|
|
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. |
|
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 |
|
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 |
|
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 |
|
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 |
|
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. |
|
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. |
|
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). |
|
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 |
|
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 |
|
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 |
|
no |
When set to the ID of an target group, retrieves only recipients included in the specified groups conditions. |
|
no |
The bounce flag of the recipient. Unavailable recipients have bounced and are not included in sending of mailing |
|
no |
Allows finding of all recipients where email contains a specific string. Case insensitive |
|
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
Returns all recipients whose family name contains any case insensitive match of Doe and last name contains any case insensitive match of LastNameValue
Can be combined with attributes filter.
Failed query Same key for attributes and attributesContainsIgnoreCase can not be used. Status code 400
Same key for attributesContainsIgnoreCase. Status code 400
|
Response structure
See section pagination.
Example without request parameters
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients?attributes=familyName&attributes=givenName&subscribedTo=10' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients?attributes=familyName&attributes=givenName&unsubscribedFrom=10' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients?email=john.doe@example.com' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients?lastModifiedSince=2018-01-16T11:42:32Z' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients?attributes=givenName&attributes=familyName&attributes.familyName=Doe' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients?trackingPermissionsForLists=3&trackingPermissionsForLists=4&trackingPermissionsForLists=5' -i -X GET
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)
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients?filterId=1' -i -X GET
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:
Parameter | Description |
---|---|
|
The ID of the resource |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/recipients/5' -i -X DELETE
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:
Parameter | Description |
---|---|
|
The ID of the list for which the recipient should be deleted. The target list must not be a list of type SYSTEM. |
|
The ID of the recipient which should be deleted from a list. |
|
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
$ curl 'https://api.inxmail.com/customer/rest/v1/lists/2/recipient/3?deleteUnsubscribed=true' -i -X DELETE
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 |
---|---|---|---|
String |
The new email address |
|
|
attributes |
Object |
Object containing the attributes to change |
|
Example by ID
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"
}
}
}
$ 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"
}
}'
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
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"
}
}
}
$ 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"
}
}'
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 |
---|---|---|---|
String |
The email address of the new recipient |
|
|
attributes |
Object |
Object containing the recipient attributes. Attributes must already exist. |
|
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
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"
}
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
Parameter | Description |
---|---|
|
The ID of the test profile |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the test profile |
|
|
The description of the test profile |
|
|
The tracking permission of the test profile |
|
|
The email address of the test profile |
|
|
The type of the test profile. Possible types are: [GLOBAL, LIST]. |
|
|
The ID of the list holding the test profile. Omitted for test profiles with type GLOBAL. |
|
|
The modification date of this test profile |
|
|
The attributes of the test recipient. Omitted if no attributes were requested. |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/test-profiles/1?allAttributes=true' -i -X GET
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:24Z",
"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 |
---|---|---|
|
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. |
|
no |
If |
|
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
$ curl 'https://api.inxmail.com/customer/rest/v1/test-profiles' -i -X GET
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-09-05T13:32:24Z",
"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-09-05T13:32:24Z",
"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-09-05T13:32:24Z",
"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-09-05T13:32:24Z",
"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
$ 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"
}'
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
$ 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"
}'
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 'https://api.inxmail.com/customer/rest/v1/test-profiles/1' -i -X DELETE
DELETE /customer/rest/v1/test-profiles/1 HTTP/1.1
Host: api.inxmail.com
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 |
---|---|---|
|
yes |
The ID of the list for which all memberships should be deleted. The target list must be a list of type STANDARD. |
|
yes |
The state of the memberships to be deleted. At the moment SUBSCRIBED is the only supported state. |
|
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
$ curl 'https://api.inxmail.com/customer/rest/v1/memberships?listId=5&state=SUBSCRIBED&recipientAttributes.attributeName=John' -i -X DELETE
HTTP/1.1 204 No Content
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
Parameter | Description |
---|---|
|
The ID of the event |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the event |
|
|
The type of the event |
|
|
The ID of the list associated to this event |
|
|
The ID of the recipient associated to this event. Currently always null. |
|
|
The point in time when this event occurred |
|
|
An identifier for the source which caused this event |
|
|
The email address of the recipient associated to this event |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/events/subscriptions/3' -i -X GET
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-09-05T13:31:39Z",
"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 |
---|---|---|
|
no |
The ID of the list to retrieve events for |
|
no |
The IDs of the lists to retrieve events for |
|
no |
The start date (inclusive) for the desired subscriptions |
|
no |
The end date (exclusive) for the desired subscriptions |
|
no |
The types for the desired subscriptions. Default is all types. |
|
no |
Indicates the relations of the resources that should be embedded in the result. |
|
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 |
---|---|
|
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
$ curl 'https://api.inxmail.com/customer/rest/v1/events/subscriptions?listId=5&startDate=2024-09-05T12:31:40Z&endDate=2024-09-05T14:31:40Z&types=PENDING_SUBSCRIPTION,PENDING_SUBSCRIPTION_DONE&embedded=inx:recipient&recipientAttributes=firstName,lastName' -i -X GET
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-09-05T13:31:40Z",
"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-09-05T13:31:40Z",
"_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-09-05T13:31:40Z",
"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-09-05T13:31:40Z",
"_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-09-05T12%3A31%3A40Z&endDate=2024-09-05T14%3A31%3A40Z&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:
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 |
|
String |
The email address of the recipient to subscribe |
|
|
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
$ 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"
}'
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
Parameter | Description |
---|---|
|
The ID of the event |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the event |
|
|
The type of the event |
|
|
The ID of the list associated to this event |
|
|
The ID of the recipient associated to this event |
|
|
The ID of the sending associated to this event |
|
|
The ID of the mailing associated to this event |
|
|
The point in time when this event occurred |
|
|
An identifier for the source which caused this event |
|
|
The email address of the recipient associated to this event |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/events/unsubscriptions/3' -i -X GET
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-09-05T13:31:41Z",
"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 |
---|---|---|
|
no |
The ID of the list to retrieve events for |
|
no |
The IDs of the lists to retrieve events for. |
|
no |
The start date (inclusive) for the desired unsubscriptions |
|
no |
The end date (exclusive) for the desired unsubscriptions |
|
no |
The types for the desired unsubscriptions. Default is all types. |
|
no |
Indicates the relations of the resources that should be embedded in the result. |
|
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 |
---|---|
|
The recipient who was unsubscribed. |
Response structure
See section pagination.
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/events/unsubscriptions?listIds=5&startDate=2024-09-05T12:31:43Z&endDate=2024-09-05T14:31:43Z&types=PENDING_UNSUBSCRIPTION_DONE,PENDING_UNSUBSCRIPTION&embedded=inx:recipient&recipientAttributes=firstName,lastName' -i -X GET
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-09-05T13:31:43Z",
"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-09-05T13:31:43Z",
"_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-09-05T13:31:43Z",
"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-09-05T13:31:43Z",
"_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-09-05T12%3A31%3A43Z&endDate=2024-09-05T14%3A31%3A43Z&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 |
|
String |
The email address of the recipient to unsubscribe |
|
|
source |
String |
An identifier for the source which caused this event |
|
suppliedRemoteAddress |
String |
The actual supplied IP address of the unsubscription request |
Example
$ 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"
}'
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
Parameter | Description |
---|---|
|
The ID of the target group |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the target group |
|
|
The name of the target group |
|
|
The description of the target group |
|
|
The ID of the list holding the target group. |
|
|
The filter condition of the target group. |
|
|
The timestamp the target-group was last modified. |
|
|
The timestamp the target-group was created. |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/target-groups/1' -i -X GET
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 |
---|---|---|
|
no |
The ID of the list to retrieve target groups for. If not specified, the target groups of all lists are returned. |
|
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
$ curl 'https://api.inxmail.com/customer/rest/v1/target-groups' -i -X GET
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 |
|
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 |
|
filterString |
String |
The filter condition of the target group |
Example
$ 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)"
}'
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
$ 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)"
}'
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 349
{
"name" : "name",
"id" : 0,
"description" : "description",
"listId" : 5,
"creationDate" : "2024-09-05T13:32:22Z",
"modificationDate" : "2024-09-05T13:32:22Z",
"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:
Parameter | Description |
---|---|
|
The ID of the target group to be deleted. |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/target-groups/7' -i -X DELETE
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
Parameter | Description |
---|---|
|
The ID of the tracking permission |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the tracking permission |
|
|
The ID of the list associated to this tracking permission |
|
|
The ID of the recipient associated to this tracking permission |
|
|
The state of this tracking permission |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/tracking-permissions/5' -i -X GET
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
Parameter | Required | Description |
---|---|---|
|
yes |
The ID of the list to retrieve tracking permissions for |
|
yes |
The ID of the recipient to retrieve tracking permissions for |
or
Parameter | Required | Description |
---|---|---|
|
yes |
The ID of the list to retrieve tracking permissions for |
|
yes |
The email address of the recipient to retrieve tracking permissions for |
Response structure
See section pagination.
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/tracking-permissions?listIds=7&recipientIds=11' -i -X GET
$ curl 'https://api.inxmail.com/customer/rest/v1/tracking-permissions?listIds=7&emails=max.mustermann@example.com' -i -X GET
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.
Path | Type | Description | Constraints |
---|---|---|---|
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 the tracking permission. Currently only GRANTED state can be posted. |
|
suppliedRemoteAddress |
String |
The actual given IP of the request. |
|
or
Path | Type | Description | Constraints |
---|---|---|---|
listId |
Number |
The ID of the list associated to this tracking permission |
|
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. |
|
Example
$ 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"
}'
$ 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"
}'
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
$ curl 'https://api.inxmail.com/customer/rest/v1/tracking-permissions?listIds=7&recipientIds=11' -i -X DELETE
$ curl 'https://api.inxmail.com/customer/rest/v1/tracking-permissions?listIds=7&emails=max.mustermann@example.com' -i -X DELETE
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 |
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
Parameter | Description |
---|---|
|
The ID of the event |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the event |
|
|
The ID of the list associated to this event |
|
|
The ID of the recipient associated to this event |
|
|
The new tracking permission state resulting from this event |
|
|
The point in time when this event occurred |
|
|
The originator that caused this event |
|
|
The originator type that caused this event |
|
|
The type of entity that caused this event |
|
|
The type of action that caused this event |
|
|
The identity of the entity that caused this event |
|
|
The remote address of the entity that caused this event, as determined by the Inxmail Professional application |
|
|
The remote address of the entity that caused this event, as supplied by a third party |
|
|
A message provided by the entity that caused this event |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/events/tracking-permissions/5' -i -X GET
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 878
{
"id" : 5,
"timestamp" : "2024-09-05T13:31:44Z",
"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 |
---|---|---|
|
no |
The IDs of the lists to retrieve events for |
|
no |
The ID of the recipient to retrieve events for |
|
no |
The email address of the recipient to retrieve events for |
|
no |
The start date (inclusive) for the desired tracking permission events |
|
no |
The end date (exclusive) for the desired tracking permission events |
|
no |
Indicates the relations of the resources that should be embedded in the result. |
|
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. |
|
no |
details of the originator that triggered this event |
Embeddable relations
Relation | Description |
---|---|
|
The recipient whose tracking permission was altered. |
Response structure
See section pagination.
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/events/tracking-permissions?listIds=7,8&recipientIds=11&startDate=2024-09-05T12:31:45Z&endDate=2024-09-05T14:31:45Z&embedded=inx:recipient&recipientAttributes=firstName,lastName&eventOriginatorTypes=RPC_API,USER_UNSUBSCRIPTION' -i -X GET
$ curl 'https://api.inxmail.com/customer/rest/v1/events/tracking-permissions?listIds=7,8&emails=email@example.com&startDate=2024-09-05T12:31:45Z&endDate=2024-09-05T14:31:45Z&embedded=inx:recipient&recipientAttributes=firstName,lastName&eventOriginatorTypes=RPC_API,USER_UNSUBSCRIPTION' -i -X GET
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 3361
{
"_embedded" : {
"inx:tracking-permission-events" : [ {
"id" : 1,
"timestamp" : "2024-09-05T13:31:45Z",
"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-09-05T13:31:45Z",
"_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-09-05T13:31:45Z",
"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-09-05T13:31:45Z",
"_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-09-05T12%3A31%3A45Z&endDate=2024-09-05T14%3A31%3A45Z&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.
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 |
|
Date only |
|
Time only |
|
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.
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 |
---|---|---|
|
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. |
|
no |
If |
|
no |
If |
|
no |
Possible values are |
|
no |
Possible values are |
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 |
---|---|
|
No recipient attributes of an existing recipient will be changed by the import. |
|
Every recipient attribute will be overwritten with the corresponding value in the CSV file, assuming the value in the CSV file is not empty. |
|
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 |
|
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 |
---|---|
|
No tracking permissions of an existing recipient will be changed by the import. |
|
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 |
|
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 |
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
$ 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'
$ 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'
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:
Parameter | Description |
---|---|
|
The Id of of the recipient import |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the recipient import |
|
|
The state of the import. Possible values are: NEW, PROCESSING, SUCCESS, FAILED, CANCELED |
|
|
The trigger type state of the import. Possible values are: |
|
|
The number of successfully imported records so far |
|
|
The current number of records which could not be imported |
|
|
The begin date of the import |
|
|
The end date of the import |
|
|
The files of the import |
|
|
The target list id of the import |
|
|
Links to other resources |
The values for the state
field have the following meaning:
State | Description |
---|---|
|
The import has been acknowledged but has not yet started processing. |
|
The import is in progress. |
|
The import has finished successfully. This does not imply that all records were successfully imported, though. |
|
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. |
|
The import was aborted by a user. |
There are the following link relations in the _links
field:
Relation | Description |
---|---|
|
Link to this recipient import |
|
Link to files of this recipient import |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/5' -i -X GET
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:
Parameter | Description |
---|---|
|
The Id of the recipient import |
|
The Id of the file |
Response structure
Path | Type | Description |
---|---|---|
|
|
The name of the file |
|
|
The state of the import. Possible values are: NEW, PREFETCHING, READY_TO_PROCESS, PREFETCH_FAILED, PROCESSING, SUCCESSFUL, FAILED, DEQUEUED, CANCELED |
|
|
The number of imported records so far |
|
|
The number of successfully imported records so far |
|
|
The current number of records which could not be imported |
|
|
The ID of the file import |
|
|
Links to other resources |
The values for the state
field have the following meaning:
State | Description |
---|---|
|
The file import has been acknowledged but has not yet started processing. |
|
File is being retrieved. Only relevant for Import Automation imports. |
|
Ready for processing. Maybe waiting for another import to finish. |
|
Failed to load the file. Only relevant for Import Automation imports. |
|
The file import is in progress. |
|
The file import has finished successfully. |
|
The file import could not be performed. |
|
The file has been removed from the queue and will not be imported. |
|
The file import was aborted by a user. |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/5/files/123' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients' -i -X GET
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-09-05T13:31:05Z",
"endDate" : "2024-09-05T13:31:05Z",
"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-09-05T13:31:05Z",
"endDate" : "2024-09-05T13:31:05Z",
"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:
Parameter | Description |
---|---|
|
The Id of the recipient import |
Response structure
See section pagination.
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/1/files' -i -X GET
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:
Parameter | Description |
---|---|
|
The Id of the recipient import |
|
The Id of the import file |
Response structure
See section pagination.
The resources will have following response structure:
Path | Type | Description |
---|---|---|
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 |
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 |
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 |
ATTRIBUTE_PARSE_ERROR |
Attribute could not be parsed. |
Check value in line |
EMAIL_PARSE_ERROR |
Email address could not be parsed. |
Check whether the value in line |
HEADER_ERROR |
Header error |
Check if the header contains valid CSV data in compliance with section Required CSV file structure. |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/1/files/1/errors' -i -X GET
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
} ]
}
}
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 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
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 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
$ 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'
HTTP/1.1 201 Created
Location: https://api.inxmail.com/customer/rest/v1/imports/recipients/store
Content-Type: application/hal+json
Content-Length: 175
{
"id" : 2,
"originalFileName" : "import.csv",
"_links" : {
"self" : {
"href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/store"
}
}
}
Path | Type | Description |
---|---|---|
|
|
The id of the file, stored to the server |
|
|
The name of the file, stored to the server |
|
|
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
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/store/2' -i -X DELETE
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" : ",",
"id" : 0,
"encoding" : "UTF-8",
"importConflictMode" : "SKIP",
"trackingPermissionConflictMode" : "KEEP_EXISTING",
"dateFormat" : "dd.MM.yyyy",
"emailAddressColumn" : "EmailAddressColumnValue",
"trackingPermissionColumnName" : "TrackingPermissionColumnName",
"notifyOnFailure" : true,
"notifyOnCancel" : true,
"notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
"columnSeparator" : ",",
"textDelimiter" : "'",
"textDelimiterEscaping" : "DOUBLE",
"resubscribeUnsubscribedRecipients" : true,
"notifyOnSuccess" : true,
"dateTimeFormat" : "dd.MM.yyyy HH:mm:ss",
"timeFormat" : "HH:mm:ss",
"thousandsSeparator" : ".",
"booleanParserPattern" : "Yes",
"booleanMatchValue" : true,
"trackingPermissionGrantedValue" : "true",
"timezone" : "UTC",
"clearListBeforeImport" : true,
"unsubscribeSubscribedRecipients" : true,
"ignoreUnknownRecipients" : true,
"targetList" : 1,
"targetListTab" : "NONE",
"_links" : {
"self" : {
"href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/12"
}
}
}
Example
$ 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",
"dateFormat" : "dd.MM.yyyy",
"timeFormat" : "HH:mm:ss",
"booleanParserPattern" : "Yes",
"targetList" : 1,
"importConflictMode" : "SKIP",
"emailAddressColumn" : "EmailAddressColumnValue",
"notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
"columnSeparator" : ",",
"notifyOnFailure" : true,
"resubscribeUnsubscribedRecipients" : true,
"timezone" : "UTC",
"decimalSeparator" : ",",
"notifyOnCancel" : true,
"ignoreUnknownRecipients" : true,
"textDelimiter" : "'",
"unsubscribeSubscribedRecipients" : true
}'
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: 1136
{
"decimalSeparator" : ",",
"id" : 0,
"encoding" : "UTF-8",
"importConflictMode" : "SKIP",
"trackingPermissionConflictMode" : "KEEP_EXISTING",
"dateFormat" : "dd.MM.yyyy",
"emailAddressColumn" : "EmailAddressColumnValue",
"trackingPermissionColumnName" : "TrackingPermissionColumnName",
"notifyOnFailure" : true,
"notifyOnCancel" : true,
"notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
"columnSeparator" : ",",
"textDelimiter" : "'",
"textDelimiterEscaping" : "DOUBLE",
"resubscribeUnsubscribedRecipients" : true,
"notifyOnSuccess" : true,
"dateTimeFormat" : "dd.MM.yyyy HH:mm:ss",
"timeFormat" : "HH:mm:ss",
"thousandsSeparator" : ".",
"booleanParserPattern" : "Yes",
"booleanMatchValue" : true,
"trackingPermissionGrantedValue" : "true",
"timezone" : "UTC",
"clearListBeforeImport" : true,
"unsubscribeSubscribedRecipients" : true,
"ignoreUnknownRecipients" : true,
"targetList" : 1,
"targetListTab" : "NONE",
"_links" : {
"self" : {
"href" : "https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/0"
}
}
}
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. |
|
trackingPermissionColumnName |
String |
The name of the column in the csv file that contains the information about the tracking permissions. |
|
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. |
|
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. |
|
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. |
|
timezone |
String |
The Time Zone for the Date Time values |
|
importConflictMode |
String |
The strategy to handle import conflicts. For more information see here |
|
trackingPermissionConflictMode |
String |
The strategy to handle tracking permissions conflicts. For more information see here |
|
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 |
|
Example
$ 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",
"dateFormat" : "dd.MM.yyyy",
"timeFormat" : "HH:mm:ss",
"booleanParserPattern" : "Yes",
"targetList" : 1,
"importConflictMode" : "SKIP",
"emailAddressColumn" : "EmailAddressColumnValue",
"notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
"columnSeparator" : ",",
"notifyOnFailure" : true,
"resubscribeUnsubscribedRecipients" : true,
"timezone" : "UTC",
"decimalSeparator" : ",",
"notifyOnCancel" : true,
"ignoreUnknownRecipients" : true,
"textDelimiter" : "'",
"unsubscribeSubscribedRecipients" : true
}'
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: 1136
{
"decimalSeparator" : ",",
"id" : 0,
"encoding" : "UTF-8",
"importConflictMode" : "SKIP",
"trackingPermissionConflictMode" : "KEEP_EXISTING",
"dateFormat" : "dd.MM.yyyy",
"emailAddressColumn" : "EmailAddressColumnValue",
"trackingPermissionColumnName" : "TrackingPermissionColumnName",
"notifyOnFailure" : true,
"notifyOnCancel" : true,
"notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
"columnSeparator" : ",",
"textDelimiter" : "'",
"textDelimiterEscaping" : "DOUBLE",
"resubscribeUnsubscribedRecipients" : true,
"notifyOnSuccess" : true,
"dateTimeFormat" : "dd.MM.yyyy HH:mm:ss",
"timeFormat" : "HH:mm:ss",
"thousandsSeparator" : ".",
"booleanParserPattern" : "Yes",
"booleanMatchValue" : true,
"trackingPermissionGrantedValue" : "true",
"timezone" : "UTC",
"clearListBeforeImport" : true,
"unsubscribeSubscribedRecipients" : true,
"ignoreUnknownRecipients" : true,
"targetList" : 1,
"targetListTab" : "NONE",
"_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. |
|
trackingPermissionColumnName |
String |
The name of the column in the csv file that contains the information about the tracking permissions. |
|
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. |
|
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. |
|
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. |
|
timezone |
String |
The Time Zone for the Date Time values |
|
importConflictMode |
String |
The strategy to handle import conflicts. For more information see here |
|
trackingPermissionConflictMode |
String |
The strategy to handle tracking permissions conflicts. For more information see here |
|
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 |
|
Example
$ 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",
"dateFormat" : "dd.MM.yyyy",
"timeFormat" : "HH:mm:ss",
"booleanParserPattern" : "Yes",
"targetList" : 1,
"importConflictMode" : "SKIP",
"emailAddressColumn" : "EmailAddressColumnValue",
"notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
"columnSeparator" : ",",
"notifyOnFailure" : true,
"resubscribeUnsubscribedRecipients" : true,
"timezone" : "UTC",
"decimalSeparator" : ",",
"notifyOnCancel" : true,
"ignoreUnknownRecipients" : true,
"textDelimiter" : "'",
"unsubscribeSubscribedRecipients" : true
}'
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1137
{
"decimalSeparator" : ",",
"id" : 0,
"encoding" : "UTF-8",
"importConflictMode" : "SKIP",
"trackingPermissionConflictMode" : "KEEP_EXISTING",
"dateFormat" : "dd.MM.yyyy",
"emailAddressColumn" : "EmailAddressColumnValue",
"trackingPermissionColumnName" : "TrackingPermissionColumnName",
"notifyOnFailure" : true,
"notifyOnCancel" : true,
"notifyRecipients" : [ "john-doe@example.com", "jane-roe@example.com" ],
"columnSeparator" : ",",
"textDelimiter" : "'",
"textDelimiterEscaping" : "DOUBLE",
"resubscribeUnsubscribedRecipients" : true,
"notifyOnSuccess" : true,
"dateTimeFormat" : "dd.MM.yyyy HH:mm:ss",
"timeFormat" : "HH:mm:ss",
"thousandsSeparator" : ".",
"booleanParserPattern" : "Yes",
"booleanMatchValue" : true,
"trackingPermissionGrantedValue" : "true",
"timezone" : "UTC",
"clearListBeforeImport" : true,
"unsubscribeSubscribedRecipients" : true,
"ignoreUnknownRecipients" : true,
"targetList" : 1,
"targetListTab" : "NONE",
"_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
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/configuration-template/12' -i -X DELETE
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.
The following path parameters are required:
Parameter | Required | Description |
---|---|---|
|
yes |
The id of an existing import file |
|
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) 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
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/preview?importFileId=12&configurationTemplateId=39' -i -X GET
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 485
{
"preview" : [ {
"name" : "John Doe",
"likesIceCream" : true,
"birthDay" : "1990-05-14",
"score" : 123.5,
"email" : "johnDoe@example.com"
}, {
"name" : "Jane Roe",
"likesIceCream" : false,
"birthDay" : "1990-12-25",
"score" : 70.3,
"email" : "janeRoe@example.com"
} ],
"_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 an import you can send a Post
request with the following parameters:
Parameter | Required | Description |
---|---|---|
|
yes |
The id of an existing import file |
|
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
.
The result will be a Status Monitor, which you can use to check the current status of the import.
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/imports/recipients/preconfigured?fileId=14&configurationId=12' -i -X POST
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-09-05T13:31:31Z",
"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
} ]
}
}
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
Parameter | Description |
---|---|
|
The ID of the bounce |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the bounce |
|
|
The ID of the associated list |
|
|
The ID of the associated mailing |
|
|
The category of the bounce |
|
|
The email address for which the bounce occured |
|
|
The ID of the recipient |
|
|
The ID of the sending |
|
|
The point in time when this bounce was processed |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/bounces/1' -i -X GET
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 661
{
"id" : 1,
"timestamp" : "2024-09-05T13:30:59Z",
"listId" : 2,
"recipientId" : 4,
"matchedEmailAddress" : "john.doe@example.com",
"sendingId" : 5,
"mailingId" : 3,
"bounceCategory" : "HARD",
"_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 |
---|---|---|
|
no |
The start date (inclusive) for the desired bounces |
|
no |
The end date (exclusive) for the desired bounces |
|
no |
The bounceCategory for the desired bounces. Default is all bounceCategories. |
|
no |
The ID of the list to retrieve bounces for |
|
no |
Indicates the relations of the resources that should be embedded in the result. |
|
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. |
|
no |
The ID of the mailing to retrieve bounces for. |
|
no |
The IDs of the sendings to retrieve bounces for. |
|
no |
The IDs of the mailings to retrieve bounces for. This parameter must not be specified at the same time as |
|
no |
The IDs of the lists to retrieve bounces for. This parameter must not be specified at the same time as |
Embeddable relations
Relation | Description |
---|---|
|
The recipient that is associated to this bounce, if known. |
Response structure
See section pagination.
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/bounces?startDate=2024-09-05T12:31:00Z&endDate=2024-09-05T14:31:00Z&embedded=inx:recipient&bounceCategory=HARD,SOFT,UNKNOWN&listId=3&mailingId=4&sendingIds=5,6&recipientAttributes=firstName,lastName' -i -X GET
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 5043
{
"_embedded" : {
"inx:bounces" : [ {
"id" : 1,
"timestamp" : null,
"listId" : 2,
"recipientId" : 4,
"matchedEmailAddress" : "john.doe_1@example.com",
"sendingId" : 5,
"mailingId" : 3,
"bounceCategory" : "SOFT",
"_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,
"matchedEmailAddress" : "john.doe_2@example.com",
"sendingId" : 6,
"mailingId" : 4,
"bounceCategory" : "HARD",
"_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,
"matchedEmailAddress" : "john.doe_3@example.com",
"sendingId" : 7,
"mailingId" : 5,
"bounceCategory" : "SOFT",
"_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,
"matchedEmailAddress" : "john.doe_4@example.com",
"sendingId" : 8,
"mailingId" : 6,
"bounceCategory" : "HARD",
"_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-09-05T12%3A31%3A00Z&endDate=2024-09-05T14%3A31%3A00Z&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
Parameter | Description |
---|---|
|
The ID of the click |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the click |
|
|
The ID of the list associated to this click |
|
|
The tracking hash of the click |
|
|
The ID of the recipient associated to this click |
|
|
The ID of the link associated to this click |
|
|
The ID of the sending associated to this click |
|
|
The ID of the mailing associated to this click |
|
|
The point in time when this click occurred |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/clicks/1' -i -X GET
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,
"sendingId" : 1,
"mailingId" : 5,
"trackingHash" : "b8c37e33defde51cf91e1e03e51657db",
"linkId" : 3,
"_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 |
---|---|---|
|
no |
The ID of the mailing to retrieve clicks for |
|
no |
The ID of the sending to retrieve clicks for |
|
no |
Indicates that only clicks where the recipient who clicked is identifiable will be returned. |
|
no |
Indicates the relations of the resources that should be embedded in the result. |
|
no |
The start date (inclusive) for the desired clicks |
|
no |
The end date (exclusive) for the desired clicks |
|
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. |
|
no |
The IDs of the mailings to retrieve clicks for. This parameter must not be specified at the same time as |
|
no |
The IDs of the lists to retrieve clicks for. This parameter must not be specified at the same time as |
Embeddable relations
Relation | Description |
---|---|
|
The recipient who clicked the link, if known. |
Response structure
See section pagination.
Example
$ 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
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,
"sendingId" : 1,
"mailingId" : 5,
"trackingHash" : "b8c37e33defde51cf91e1e03e51657db",
"linkId" : 11,
"_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,
"sendingId" : 1,
"mailingId" : 5,
"trackingHash" : "b8c1337adefde51cf91e1e03e51657db",
"linkId" : 11,
"_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
Parameter | Description |
---|---|
|
The ID of the web beacon hit |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the web beacon hit |
|
|
The ID of the list associated to this web beacon hit |
|
|
The tracking hash of the web beacon hit |
|
|
The ID of the recipient associated to this web beacon hit |
|
|
The ID of the link associated to this web beacon hit |
|
|
The ID of the sending associated to this web beacon hit |
|
|
The ID of the mailing associated to this web beacon hit |
|
|
The point in time when this web beacon hit occurred |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/web-beacon-hits/1' -i -X GET
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,
"sendingId" : 1,
"mailingId" : 5,
"trackingHash" : "b8c37e33defde51cf91e1e03e51657db",
"linkId" : 3,
"_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 |
---|---|---|
|
no |
The ID of the mailing to retrieve clicks for |
|
no |
The ID of the sending to retrieve clicks for |
|
no |
Indicates that only web beacon hits where the recipient who triggered the hit is identifiable will be returned. |
|
no |
Indicates the relations of the resources that should be embedded in the result. |
|
no |
The start date (inclusive) for the desired clicks |
|
no |
The end date (exclusive) for the desired clicks |
|
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. |
|
no |
The IDs of the mailings to retrieve clicks for. This parameter must not be specified at the same time as |
|
no |
The IDs of the lists to retrieve clicks for. This parameter must not be specified at the same time as |
Embeddable relations
Relation | Description |
---|---|
|
The recipient who triggered the web beacon hit, if known |
Response structure
See section pagination.
Example
$ 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
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,
"sendingId" : 1,
"mailingId" : 5,
"trackingHash" : "b8c37e33defde51cf91e1e03e51657db",
"linkId" : 11,
"_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,
"sendingId" : 1,
"mailingId" : 5,
"trackingHash" : "b8c1337adefde51cf91e1e03e51657db",
"linkId" : 11,
"_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 |
---|---|
|
Blocks the address |
|
Blocks all addresses under the domain |
|
Blocks all addresses with a local part of |
Retrieve single blacklist entry
GET /blacklist-entries/{id}
A GET
request with a ID parameter will return the requested blacklist entry.
Request structure
Parameter | Description |
---|---|
|
The ID of the blacklist entry |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the blacklist entry |
|
|
The pattern for email addresses blocked by this blacklist entry |
|
|
A descriptive text for this blacklist entry |
|
|
The last modification date of the blacklist entry |
|
|
The number of import attempts that were blocked by this blacklist entry |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/blacklist-entries/5' -i -X GET
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
$ curl 'https://api.inxmail.com/customer/rest/v1/blacklist-entries?lastModifiedSince=2018-01-16T11:42:32Z&patternContainsIgnoreCase=*' -i -X GET
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 |
---|---|---|
|
yes |
The pattern for email addresses blocked by this blacklist entry which should be deleted. |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/blacklist-entries/?pattern=john.doe@example.com' -i -X DELETE
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.66/xpro-rest-impl/build/generated-snippets/delete-existing-blacklist-entry-by-id/request-parameters.adoc[]
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/blacklist-entries/1' -i -X DELETE
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 |
---|---|---|
|
|
The number of import attempts that were blocked by this blacklist entry |
|
|
The pattern for email addresses blocked by this blacklist entry |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/blacklist-entries/preview?pattern=abc' -i -X GET
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 |
|
description |
String |
A description to the describe this blacklist entry |
|
Example
$ 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"
}'
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 |
|
description |
String |
A description to describe this blacklist entry |
|
Example
$ 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"
}'
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 |
---|---|---|
|
yes |
The ID of the mailing |
Response structure
Path | Type | Description |
---|---|---|
|
|
Number of opening recipients. Opening: First unique click or graphic loaded in the email. |
|
|
Number of interactions by bots. Interaction: First graphic loaded in the email by a bot. |
|
|
Opening rate: Number of opening recipients / number of net recipients |
|
|
Total clicks |
|
|
Number of clicking recipients |
|
|
Unique click rate: Number of clicking recipients / number of net recipients |
|
|
CTOR: Number of clicking recipients / number of opening recipients |
|
|
Number of unsubscribe clicks |
|
|
Number of unsubscribe clicks via list unsubscribe |
|
|
Unsubscribe rate |
|
|
Statistics by each link |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/statistics/responses?mailingId=5' -i -X GET
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 |
---|---|---|
|
yes |
The ID of the mailing |
|
no |
Include the total clicks and more information for each of links |
Response structure
Path | Type | Description |
---|---|---|
|
|
Number of opening recipients. Opening: First unique click or graphic loaded in the email. |
|
|
Number of interactions by bots. Interaction: First graphic loaded in the email by a bot. |
|
|
Opening rate: Number of opening recipients / number of net recipients |
|
|
Total clicks |
|
|
Number of clicking recipients |
|
|
Unique click rate: Number of clicking recipients / number of net recipients |
|
|
CTOR: Number of clicking recipients / number of opening recipients |
|
|
Number of unsubscribe clicks |
|
|
Number of unsubscribe clicks via list unsubscribe |
|
|
Unsubscribe rate |
|
|
Statistics by each link |
|
|
Id of the link |
|
|
Report name of the link |
|
|
Url of the link |
|
|
Amount of total clicks by the link |
|
|
Type of the link |
|
|
Amount of unique clicks by the link (could be null in case unique click feature is not supported by the LinkType ) |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/statistics/responses?mailingId=5&includeLinkData=true' -i -X GET
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 |
---|---|---|
|
yes |
The ID of the mailing |
|
no |
Include the total clicks and more information for each of links |
|
no |
Include the clicks by type data, includeLinkData must be true |
Response structure
Path | Type | Description |
---|---|---|
|
|
Number of opening recipients. Opening: First unique click or graphic loaded in the email. |
|
|
Number of interactions by bots. Interaction: First graphic loaded in the email by a bot. |
|
|
Opening rate: Number of opening recipients / number of net recipients |
|
|
Total clicks |
|
|
Number of clicking recipients |
|
|
Unique click rate: Number of clicking recipients / number of net recipients |
|
|
CTOR: Number of clicking recipients / number of opening recipients |
|
|
Number of unsubscribe clicks |
|
|
Number of unsubscribe clicks via list unsubscribe |
|
|
Unsubscribe rate |
|
|
Statistics by each link |
|
|
Id of the link |
|
|
Report name of the link |
|
|
Url of the link |
|
|
Amount of total clicks by the link |
|
|
Type of the link |
|
|
Amount of unique clicks by the link (could be null in case unique click feature is not supported by the LinkType ) |
|
|
Clicks by type |
|
|
Type of client where the click was made, can be: MOBILE, DESKTOP, WEB, AMBIGUOUS OR UNKOWN |
|
|
Total clicks of this type |
|
|
Unique clicks of this type |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/statistics/responses?mailingId=5&includeLinkData=true&includeTypeData=true' -i -X GET
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 |
---|---|---|
|
yes |
The ID of the mailing. |
Response structure
Path | Type | Description |
---|---|---|
|
|
Number of recipients. |
|
|
Number of successfully delivered sendings. |
|
|
Number of bounces (hard bounces, soft bounces, spam bounces and unknown bounces and rejections). |
|
|
Number of sending errors. |
|
|
Number of not sent sendings. |
|
|
Sending speed as sent mails per hour. |
|
|
Average mail size in bytes. |
|
|
Point in time when sending started. |
|
|
Point in time when sending ended. |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/statistics/sendings?mailingId=1' -i -X GET
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
Parameter | Description |
---|---|
|
The ID of the text module |
Embeddable relations
Relation | Description |
---|---|
|
The text and html content of the text module |
|
The dynamic parameter used in the requested text module |
|
The recipient attributes used in the requested text module |
Response structure
Path | Type | Description |
---|---|---|
|
|
The ID of the text module |
|
|
The name of the text module |
|
|
The listId of the text module |
|
|
the timestamp when the text module was last updated |
|
|
the timestamp when the text module was created |
|
|
The content format type of the module. Possible Types: [HTML, TEXT, TEXT_HTML] |
|
|
Links to other resources |
Example
$ curl 'https://api.inxmail.com/customer/rest/v1/text-modules/1' -i -X GET
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 |
---|---|---|
|
no |
The ID of the list to retrieve text modules for. To receive the global text modules use listId=1. |
|
no |
The date filter for last modified date. |
|
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 |
---|---|
|
The dynamic parameters used in the requested text module |
Response structure
See section pagination.
Example
$ 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'
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 |
---|---|---|---|