Inxmail Commerce API
Inxmail Commerce API allows you to trigger transaction event workflows and retrieve information about the outcomes of these transactions.
Authentication
New Authentication
Inxmail Commerce API supports a new authentication method for API credentials created via the Inxmail Account Management (e.g. for Platform Accounts). These API Credentials can only be used for Spaces created and linked with the Inxmail Platform. For Authentication without Inxmail Platform see the section Old Authentication below.
For instructions on how to create new API credentials, please refer to the online help:
-
[DE] https://help.inxmail.com/de/content/xnew/inxmail_id/api-zugaenge_anlegen.htm
-
[EN] https://help.inxmail.com/en/content/xnew/inxmail_id/api-zugaenge_anlegen.htm
When using API credentials created via the Inxmail Account Management, requests must be sent to the following base URL, which consists of the space name and the API base domain:
{platform-space}.api.inxmail.com/api-service/v1/*
curl -u 'keyid:secret' -H 'Accept: application/json' 'https://{platform-space}.api.inxmail.com/api-service/v1/bounces'The API credentials must be authorized for the corresponding space. Depending on the type of space, the following access rights are required:
-
Mail Relay: Inxmail REST API for Mail Relay
-
Transactional Mails: Inxmail REST API for Transactional Mails
-
Combined Spaces: Inxmail REST API for Transactional Mails and Mail Relay
Please note: Examples in this documentation still use the old base URL.
Old Authentication
Please Note: Preemptive Authentication is required to use the Inxmail Commerce Administration API.
Inxmail Commerce API requires REST clients to authenticate themselves with an API key using HTTP Basic Authentication.
The key consists of a keyid and a secret, which can be supplied to the client software as username and password:
curl -u 'keyid:secret' -H 'Accept: application/json' 'https://space.api.inxmail-commerce.com/api-service/v1/bounces'Media Types
Inxmail Commerce API uses JSON as data format for requests and responses. Where applicable, the HAL media format is used to form the JSON structure.
Large responses are paginated, in this case the standard next and previous link relations are used to provide navigation.
Both application/json and application/hal+json media type declarations are accepted for content negotiation.
The response uses application/hal+json if requested in the Accept: header, application/json otherwise.
Error States
The common HTTP Response Status Codes are used.
General Information ¶
All Requests ¶
All RequestsGET/
All requests are scoped to a single Inxmail Commerce space. The space ID is specified as first part of the domain name.
Example URI
- spaceid
string(required) Example: a-spaceID of the Inxmail Commerce space
404Space with specified ID does not exist
Body
{
"timestamp": "2015-08-21T06:05:30.257+0000",
"status": 404,
"error": "Not Found",
"message": "Unknown tenant.",
"path": "/v1/state"
}Entry Point ¶
Entry PointGET/v1
curl -u 'keyid:secret' -H 'Accept: application/json' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1'The entry point offers links to the existing resources.
Example URI
200Body
{
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1"
},
"triggerEvent": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/events"
},
"triggerEventAsMultipart": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/eventsasmultipart"
},
"state": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/state/{id}",
"templated": true
},
"reactions": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/reactions"
},
"bounces": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/bounces"
},
"relayBounces": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relaybounces"
}
}
}Event ¶
Trigger an Event ¶
Trigger an EventPOST/v1/events
Trigger event based on your data. There is an initial validation on reception which checks:
-
the event type exists in the Inxmail Commerce space
-
the payload contains a valid email address as value for the key that corresponds to the recipient email address in this event type
-
the size of one attachment or embedded image, and the overall size of all attachments and embedded images must not exceed 6MB
If the initial validation is successful, the event will be processed asynchronously.
All toplevel nodes, currently “event”, “attachments” and “payload” must start with lower case letter. The payload nodes must comply with the event description specified in Inxmail Commerce. Payload nodes must start with upper case letter and can be nested up to three levels.
Attachments
The attachment nodes must contain a filename, content-type and content. The content field must be a BASE64 encoded string.
Embedded images
Embedded images are supplied as values for placeholders of type “embedded image”, as a node similar to one attachment node. See below for an example. The embedded image nodes must contain a name, content-type and content. The content field must be a BASE64 encoded string.
Transactional Safety
Some origin systems and network infrastructure might lead to repeated submission of exactly the same event. Such repeated submissions can be ignored if
the request contains a unique transaction identifier. If this identifier is set, only the first event with the identical triplet of event
type, recipient email and transaction identifier will be accepted. Further events within 72 hours will be rejected with HTTP status 409 Conflict.
The transaction identifier is optional and submitted as JSON property transactionId.
curl -X POST -u 'keyid:secret' -H 'Content-Type: application/json' -d '{ "event": "MagentoNewOrder","payload": {"Customer": { "Email": "email@invalid.invalid", "Id" :"123" }, "Order": { "CustomerEmail":"email@invalid.invalid"}}, "attachments":[{"filename":"attachment1.pdf", "content-type":"application/pdf", "content":"YXNkZnNhZGZhc2Rm"},{"filename":"attachment2.pdf", "content-type":"application/pdf", "content":"YXNkZnNhZGZhc2Rm"}]}' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/events'Example URI
Example with attachmentsBody
{
"event": "neworder",
"payload": {
"Customer": {
"Id": "customer_xyz",
"Email": "customer@email.invalid",
"IsNewCustomer": true
},
"Order": {
"Id": 1,
"Date": "2015-01-27T10:25:00.000Z"
},
"Items": [
{
"Sku": "abc234",
"Name": "Sunshine Umbrella",
"Price": 19.99,
"Currency": "EUR"
},
{
"Sku": "abc123",
"Name": "Product 2",
"Price": 20.99,
"Currency": "EUR"
}
]
},
"attachments": [
{
"filename": "invoice.pdf",
"content-type": "application/pdf",
"content": "YXNkZnNhZGZhc2Rm"
},
{
"filename": "legal.pdf",
"content-type": "application/pdf",
"content": "YXNkZnNhZGZhc2Rm"
}
]
}Example with embedded imagesBody
{
"event": "exampleEmbeddedImages",
"payload": {
"Customer": {
"Email": "user@domain.invalid"
},
"ExampleForSingleEmbeddedImage": {
"QrCode": {
"name": "image.jpg",
"content-type": "image/jpeg",
"content": "Base64 encoded image"
}
},
"ExampleForListEmbeddedImage": [
{
"ProductImage": {
"name": "image.jpg",
"content-type": "image/jpeg",
"content": "Base64 encoded image"
}
},
{
"ProductImage": {
"name": "image.jpg",
"content-type": "image/jpeg",
"content": "Base64 encoded image"
}
},
{
"ProductImage": {
"name": "image.jpg",
"content-type": "image/jpeg",
"content": "Base64 encoded image"
}
}
]
}
}Example with transaction identifierBody
{
"event": "neworder",
"transactionId": "1234",
"payload": {
"Customer": {
"Id": "customer_xyz",
"Email": "customer@email.invalid",
"IsNewCustomer": true
},
"Order": {
"Id": 1,
"Date": "2015-01-27T10:25:00.000Z"
},
"Items": [
{
"Sku": "abc234",
"Name": "Sunshine Umbrella",
"Price": 19.99,
"Currency": "EUR"
},
{
"Sku": "abc123",
"Name": "Product 2",
"Price": 20.99,
"Currency": "EUR"
}
]
}
}200Request has been transmitted successfully. Returned id is the transaction id for this request.
Body
{
"id": "5534f2f3fcb24820d52f3413",
"acceptedDate": "2015-04-20T12:37:07.299+0000",
"_links": {
"state": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/state/5534f2f3fcb24820d52f3413"
}
}
}400Invalid or incomplete request body or invalid attachments
Headers
Content-Type: application/jsonBody
{
"timestamp": "2023-03-01T14:34:36.179+00:00",
"status": 400,
"error": "Bad Request",
"exception": "org.springframework.validation.BindException",
"errors": [
{
"codes": [
"event.event-must-exist-in-space.event.event",
"event.event-must-exist-in-space.event",
"event.event-must-exist-in-space.java.lang.String",
"event.event-must-exist-in-space"
],
"arguments": [
"exampleArgument"
],
"defaultMessage": " event type must exist in this space",
"objectName": "event",
"field": "event",
"rejectedValue": "illegalValue",
"bindingFailure": false,
"code": "event.event-must-exist-in-space"
}
],
"message": "Validation failed for object='event'. Error count: 1",
"path": "/api-service/v1/events/"
}409Repeated submission for same transaction
Headers
Content-Type: application/jsonBody
{
"timestamp": "2018-06-14T13:05:22.206+0000",
"status": 409,
"error": "Conflict",
"exception": "com.inxmail.xcom.api.event.RepeatedEventTransaction",
"message": "Repeated transaction for Event: 5b226811433a0a17f1900be7, Transaction ID: 1234, Recipient: customer@email.invalid"
}413Attachment(s) exceeds allowed size
Headers
Content-Type: application/jsonBody
{
"timestamp": "2023-03-01T14:34:36.179+00:00",
"status": 413,
"error": "Payload Too Large",
"exception": "com.inxmail.xcom.api.event.AttachmentToBig",
"message": "File exceeds limit of 6291456."
}500Technical error while processing the request. The same request may succeed at other times.
Headers
Content-Type: application/jsonBody
{
"timestamp": "2023-03-01T14:34:36.179+00:00",
"status": 500,
"error": "Internal Server Error",
"exception": "java.lang.RuntimeException",
"message": "java.io.IOException: IO ERROR",
"path": "/api-service/v1/events/"
}Trigger Event as Multipart ¶
Trigger Event as MultipartPOST/v1/eventsasmultipart
It is also possible to send your request as a multipart request.
curl -X POST -u 'keyid:secret' -H 'Content-Type: multipart/mixed' -F 'event={ "event": "MagentoNewOrder","payload": {"Customer": { "Email": "email@invalid.invalid", "Id" :"123" }, "Order": { "CustomerEmail":"email@invalid.invalid"}}};type=application/json' -F 'attachments=@/attachment.pdf;type=application/pdf' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/eventsasmultipart'Example URI
Headers
Content-Type: multipart/mixed, boundary=AaB03xBody
--AaB03x
Content-Disposition: form-data; name="event"
Content-Type: application/json
{
"event" : "neworder",
"payload": {
"Customer": {
"Id" : "customer_xyz",
"Email" : "customer@email.invalid",
"IsNewCustomer" : true
},
"Order": {
"Id" : 1,
"Date" : "2015-01-27T10:25:00.000Z"
},
"Items": [
{
"Sku" : "abc234",
"Name" : "Sunshine Umbrella",
"Price" : 19.99,
"Currency": "EUR"
},
{
"Sku" : "abc123",
"Name" : "Product 2",
"Price" : 20.99,
"Currency": "EUR"
}
]
}
}
--AaB03x
Content-Disposition: form-data; name="attachments"; filename="invoice.pdf"
Content-Type: application/pdf
YXNkZnNhZGZhc2Rm
--AaB03x
Content-Disposition: form-data; name="attachments"; filename="legal.pdf"
Content-Type: application/pdf
YXNkZnNhZGZhc2Rm
--AaB03x--200Request has been transmitted successfully. Returned id is the transaction id for this request.
Body
{
"id": "5534f2f3fcb24820d52f3413",
"acceptedDate": "2015-04-20T12:37:07.299+0000",
"_links": {
"state": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/state/5534f2f3fcb24820d52f3413"
}
}
}400Invalid or incomplete request body (json eventdata)
Headers
Content-Type: application/jsonBody
{
"timestamp": "2023-03-01T14:34:36.179+00:00",
"status": 400,
"error": "Bad Request",
"exception": "org.springframework.validation.BindException",
"errors": [
{
"codes": [
"event.event-must-exist-in-space.event.event",
"event.event-must-exist-in-space.event",
"event.event-must-exist-in-space.java.lang.String",
"event.event-must-exist-in-space"
],
"arguments": [
"exampleArgument"
],
"defaultMessage": " event type must exist in this space",
"objectName": "event",
"field": "event",
"rejectedValue": "illegalValue",
"bindingFailure": false,
"code": "event.event-must-exist-in-space"
}
],
"message": "Validation failed for object='event'. Error count: 1",
"path": "/api-service/v1/eventsasmultipart/"
}409Repeated submission for same transaction
Headers
Content-Type: application/jsonBody
{
"timestamp": "2018-06-14T13:05:22.206+0000",
"status": 409,
"error": "Conflict",
"exception": "com.inxmail.xcom.api.event.RepeatedEventTransaction",
"message": "Repeated transaction for Event: 5b226811433a0a17f1900be7, Transaction ID: 1234, Recipient: customer@email.invalid"
}413Attachment(s) exceeds allowed size
Headers
Content-Type: application/jsonBody
{
"timestamp": "2023-03-01T14:34:36.179+00:00",
"status": 413,
"error": "Payload Too Large",
"exception": "org.springframework.web.multipart.MultipartException",
"message": "Could not parse multipart servlet request; nested exception is java.lang.IllegalStateException: org.apache.tomcat.util.http.fileupload.FileUploadBase$SizeLimitExceededException: the request was rejected because its size (16956517) exceeds the configured maximum (6291456)"
}500Technical error while processing the request. The same request may succeed at other times.
Headers
Content-Type: application/jsonBody
{
"timestamp": "2023-03-01T14:34:36.179+00:00",
"status": 500,
"error": "Internal Server Error",
"exception": "java.lang.RuntimeException",
"message": "java.io.IOException: IO ERROR",
"path": "/api-service/v1/eventsasmultipart/"
}Request Event State ¶
Request Event StateGET/v1/state/{id}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/state/{id}'Request the state of a transaction based on the transaction id. As a result you receive the state for each mailing in the workflow for the given transaction id. As the execution of a workflow may take time, the result of a call can change over time, until the result contains the value true for the property endReached.
Example URI
- id
string(required) Example: 55d6c48b3004b15caffc0f15transaction ID for which the state should be returned, the transaction ID is returned in the result of a /v1/event or /v1/eventsasmultipart request
200The eventState contains one element for each sending attempt. The sendState of each element is one of:
-
sent- Email was sent -
blocked- Sending was blocked due to blacklist or blocklist entry of the recipients email address -
ecg_blocked- Sending was blocked due to ecg-list entry -
failed- Sending failed. For further information see the online help for the Error Log
Body
{
"id": "55d6c48b3004b15caffc0f15",
"acceptedDate": "2015-08-21T06:26:19.445+0000",
"endReached": true,
"eventState": [
{
"mailingId": "55d6c48b3004b15caffc0f16",
"sendState": "sent",
"sendDate": "2015-08-21T06:26:19.393+0000",
"sendingId": "55d6c48b3004b15caffc0f18"
},
{
"mailingId": "55d6c48b3004b15caffc0f17",
"sendState": "sent",
"sendDate": "2015-08-21T06:26:19.404+0000",
"sendingId": "53be5dd8e4b0ea715ab0f8b4"
},
{
"mailingId": "55d6c48b3004b15caffc0f18",
"sendState": "sent",
"sendDate": "2015-08-21T06:26:19.408+0000",
"sendingId": "562e088fe4b05dce974f5d70"
},
{
"mailingId": "55d6c48b3004b15caffc0f19",
"sendState": "sent",
"sendDate": "2015-08-21T06:26:19.411+0000",
"sendingId": "55d6c48b3004b15caffc0f17"
},
{
"mailingId": "55d6c48b3004b15caffc0f20",
"sendState": "blocked"
},
{
"mailingId": "55d6c48b3004b15caffc0f22",
"sendState": "ecg_blocked"
},
{
"mailingId": "55d6c48b3004b15caffc0f21",
"sendState": "failed",
"detail": "Detailed error message"
}
],
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/state/55d6c48b3004b15caffc0f15"
}
}
}400id in wrong format
Body
{
"exception": "org.springframework.core.convert.ConversionFailedException",
"path": "/api-service/v1/state/abc",
"error": "Bad Request",
"message": "Failed to convert from type [java.lang.String] to type [@org.springframework.web.bind.annotation.PathVariable org.bson.types.ObjectId] for value 'abc'; nested exception is java.lang.IllegalArgumentException: invalid hexadecimal representation of an ObjectId: [abc]",
"timestamp": "2023-03-01T14:34:14.407+00:00",
"status": 400
}404transaction with this id does not exist
Body
{
"exception": "com.inxmail.xcom.api.state.EventDataNotFound",
"path": "/api-service/v1/state/5666b8bed4c6022b03786b72",
"error": "Not Found",
"message": "Event data with id: 5666b8bed4c6022b03786b72 not found",
"timestamp": "2023-03-01T14:34:36.179+00:00",
"status": 404
}Eventtype ¶
The following resources supply information about all available eventtypes. Result sizes may be large, in that case the responses will contain only “pages” with a limited number of results.
Further pages can be retrieved by following the next (or previous) links. These links will contain the page and size request parameters as described below. For the initial request, these parameters are not required.
Eventtypes ¶
EventtypesGET/v1/eventtypes
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/eventtypes'Get information about eventtypes that are available. Returns an entry per eventtype.
The filtering parameters are all optional. If not specified, all reactions are returned.
The pagination parameters page and size should be used together, and apply within filtered results.
Example URI
- name
string(optional) Example: EventIdentifierfilters by the EventIdentifier used to trigger events for this eventtype.
- size
number(optional) Default: 200 Example: 200number of elements returned in a single response page (max. 500)
- page
number(optional) Default: 0 Example: 0result page number, if the request returns more results than the page size
200Headers
Content-Type: application/jsonBody
{
"_embedded": {
"eventtypes": [
{
"eventTypeId": "5812e8d130049f950f8e3fb5",
"name": "Event1",
"customerEmail": "Customer.Email",
"customerMapping": "Customer.Id",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/eventtypes/5812e8d130049f950f8e3fb5"
}
}
},
{
"eventTypeId": "5812e8d130049f950f8e3fb6",
"name": "Event2",
"customerEmail": "Customer.Email",
"customerMapping": "Customer.Id",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/eventtypes/5812e8d130049f950f8e3fb6"
}
}
},
{
"eventTypeId": "5812e8d130049f950f8e3fb7",
"name": "Event3",
"customerEmail": "Customer.Email",
"customerMapping": "Customer.Id",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/eventtypes/5812e8d130049f950f8e3fb7"
}
}
}
]
},
"_links": {
"first": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/eventtypes?page=0&size=2"
},
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/eventtypes"
},
"next": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/eventtypes?page=1&size=2"
},
"last": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/eventtypes?page=1&size=2"
}
},
"page": {
"size": 2,
"totalElements": 3,
"totalPages": 2,
"number": 0
}
}Single Eventtype ¶
Single EventtypeGET/v1/eventtypes/{eventTypeId}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/eventtypes/5812e8d130049f950f8e3fb5'Get information about a single eventtype.
Example URI
- eventTypeId
string(required) Example: 5812e8d130049f950f8e3fb5a single eventTypeId
200Headers
Content-Type: application/jsonBody
{
"eventTypeId": "5812e8d130049f950f8e3fb5",
"name": "Event2",
"customerEmail": "Customer.Email",
"customerMapping": "Customer.Id",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/eventtypes/5812ee113004f2b47c2b54be"
},
"eventtypes": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/eventtypes"
}
}
}400ID has an invalid format
Body
{
"exception": "org.springframework.core.convert.ConversionFailedException",
"path": "/api-service/v1/eventtypes/abc",
"error": "Bad Request",
"message": "Failed to convert from type [java.lang.String] to type [@org.springframework.web.bind.annotation.PathVariable org.bson.types.ObjectId] for value 'abc'; nested exception is java.lang.IllegalArgumentException: invalid hexadecimal representation of an ObjectId: [abc]",
"timestamp": "2023-02-16T12:44:55.415+00:00",
"status": 400
}404A eventType with this ID does not exist
Body
{
"exception": "com.inxmail.xcom.api.event.EventTypeNotFound",
"path": "/api-service/v1/eventtypes/5812f02d3004ff59a860e585",
"error": "Not Found",
"message": "EventType with id 5812f02d3004ff59a860e585 not found",
"timestamp": "2023-02-16T12:49:45.255+00:00",
"status": 404
}Sending ¶
The following resources supply information about sent emails. Result sizes may be large, in that case the responses will contain only “pages” with a limited number of results.
Further pages can be retrieved by following the next (or previous) links. These links will contain the page and size request parameters as described below. For the initial request, these parameters are not required.
Sendings ¶
SendingsGET/v1/sendings{?event,eventId,customerId,email,begin,end,page,size}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/sendings'
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/sendings?email=recipient1@fullbounce.invalid'Get information about sent transaction emails. Returns an entry per single email.
The filtering parameters are all optional. If not specified, all reactions are returned.
The pagination parameters page and size should be used together, and apply within filtered results.
Example URI
- event
string(optional) Example: 5451f3b1e1c2485a5b71ca88filters by the ID of the event type configuration
- eventId
string(optional) Example: 5534f2f3fcb24820d52f3413filters by the ID of a single transaction (as returned by /v1/event or /v1/eventsasmultipart)
- customerId
string(optional) Example: customer_xyzfilter by the customer ID that was specified in the event data
string(optional) Example: recipient@fullbounce.invalidfilters by the recipient email address (case insensitive, specify without personal part)
- begin
string(optional) Example: 2015-10-21T11:00:33.000Zfilters sendings starting from this timestamp, in ISO-8601 format
- end
string(optional) Example: 2015-10-21T11:00:33.000Zfilters sendings until this timestamp, in ISO-8601 format
- size
number(optional) Default: 200 Example: 200number of elements returned in a single response page (max. 500)
- page
number(optional) Default: 0 Example: 0result page number, if the request returns more results than the page size
200Headers
Content-Type: application/jsonBody
{
"_embedded": {
"sendings": [
{
"sendingId": "56273e11d4c62cdd1be684f1",
"sendDate": "2015-10-21T07:26:09.147+0000",
"email": "recipient1@fullbounce.invalid",
"event": "5451f3b1e1c2485a5b71ca88",
"eventId": "56273dfbd4c6edc9107ec95c",
"customerId": "customer_xyz",
"mailingId": "56273dfbd4c6edc9107ec84d",
"mailingName": "Order Confirmation",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/sendings/56273e11d4c62cdd1be684f1"
},
}
},
{
"sendingId": "56273e11d4c62cdd1be684f1",
"sendDate": "2015-10-21T07:26:09.147+0000",
"email": "recipient2@fullbounce.invalid",
"event": "5451f3b1e1c2485a5b71ca88",
"eventId": "56273dfbd4c6edc9107ec95c",
"customerId": "customer_abc",
"mailingId": "56273dfbd4c6edc9107ec82e",
"mailingName": "Additional Offers",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/sendings/56273e11d4c62cdd1be684f1"
},
}
}
]
},
"_links": {
"first": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/sendings?page=0&size=200"
},
"last": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/sendings?page=29&size=200"
},
"next": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/sendings?page=1&size=200"
},
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/sendings"
}
},
"page": {
"number": 0,
"size": 200,
"totalElements": 5911,
"totalPages": 30
}
}400invalid filter parameters, like invalid begin and end dates, invalid reaction type
Body
{
"error": "Bad Request",
"exception": "com.inxmail.xcom.api.rest.InvalidDateParameter",
"message": "Start date 2015-10-24T11:20:14.887+0000 is in future",
"path": "/api-service/v1/sendings?begin=2015-10-24T11:20:14.887%2B0000",
"status": 400,
"timestamp": "2015-10-23T11:22:01.827+0000"
}Single Sending ¶
Single SendingGET/v1/sendings/{id}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/sendings/56273e11d4c62cdd1be684f1'Get information about a single sent transaction email.
Example URI
- id
string(required) Example: 56273e12d4c62cdd1be68506a single sending ID (as included in an
eventStateentry in /v1/state/{id})
200Headers
Content-Type: application/jsonBody
{
"sendingId": "56273e11d4c62cdd1be684f1",
"sendDate": "2015-10-21T07:26:09.147+0000",
"email": "recipient1@fullbounce.invalid",
"event": "5451f3b1e1c2485a5b71ca88",
"eventId": "56273dfbd4c6edc9107ec95c",
"customerId": "customer_xyz",
"mailingId": "56273dfbd4c6edc9107ec84d",
"mailingName": "Order Confirmation",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/sendings/56273e11d4c62cdd1be684f1"
},
"sendings": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/sendings"
}
}
}400ID has an invalid format
Body
{
"exception": "org.springframework.core.convert.ConversionFailedException",
"path": "/api-service/v1/sendings/abc",
"error": "Bad Request",
"message": "Failed to convert from type [java.lang.String] to type [@org.springframework.web.bind.annotation.PathVariable org.bson.types.ObjectId] for value 'abc'; nested exception is java.lang.IllegalArgumentException: invalid hexadecimal representation of an ObjectId: [abc]",
"timestamp": "2023-02-16T12:50:20.925+00:00",
"status": 400
}404A sending with this ID does not exist
Body
{
"exception": "com.inxmail.xcom.api.sendinginfo.SendingNotFound",
"path": "/api-service/v1/sendings/5666b8bed4c6022b03786b72",
"error": "Not Found",
"message": "Sending with id 5666b8bed4c6022b03786b72 not found",
"timestamp": "2023-02-16T12:50:52.966+00:00",
"status": 404
}Reaction Data ¶
The following resources supply information about reactions or results of events or mails. Result sizes may be large, in that case the responses will contain only “pages” with a limited number of results.
Further pages can be retrieved by following the next (or previous) links. These links will contain the page and size request parameters as described below. For the initial request, these parameters are not required.
Recipient Reactions ¶
Recipient ReactionsGET/v1/reactions{?reactionType,event,eventId,mailingId,sendingId,customerId,email,begin,end,page,size,trackingHash}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/reactions'
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/reactions?reactionType=open'Get information about recipient reactions (opened email, clicked link). Returns every single reaction as separate entry, i.e. one entry per individual click, even for multiple clicks of the same recipient on the same link.
The filtering parameters are all optional. If not specified, all reactions are returned.
Enabling anonymous tracking removes the fields email, eventId, sendingId, customerId and sendDate from the response body. This should be considered when filtering reactions.
The pagination parameters page and size should be used together, and apply within filtered results.
Example URI
- reactionType
enum(optional) Example: clickfilters by the type of reaction
Choices:
openclick- event
string(optional) Example: 5451f3b1e1c2485a5b71ca88filters by the ID of the event type configuration
- eventId
string(optional) Example: 5534f2f3fcb24820d52f3413filters by the ID of a single transaction (as returned by /v1/events or /v1/eventsasmultipart)
- sendingId
string(optional) Example: 56273e12d4c62cdd1be68506filters by the ID of the sending of a mail (as included in an
eventStateentry in /v1/state/{id})- mailingId
string(optional) Example: 5614e5e6d4c676adce44f1e8filters by the ID of the mailing
- customerId
string(optional) Example: customer_xyzfilters by the customer ID that was specified in the event data
string(optional) Example: recipient@fullbounce.invalidfilters by the recipient email address (case insensitive, specify without personal part)
- begin
string(optional) Example: 2015-10-21T11:00:33.000Zfilters reactions starting from this timestamp, in ISO-8601 format
- end
string(optional) Example: 2015-10-21T11:00:33.000Zfilters reactions until this timestamp, in ISO-8601 format
- trackingHash
string(optional) Example: hU9kL-FT0kCLA960filters by the tracking hash
- size
number(optional) Default: 200 Example: 200number of elements returned in a single response page (max. 500)
- page
number(optional) Default: 0 Example: 0result page number, if the request returns more results than the page size
200reactionType is one of:
-
open- Mailing was opened by the recipient -
click- Link was clicked by the recipient
Headers
Content-Type: application/jsonBody
{
"_embedded": {
"reactions": [
{
"reactionType": "click",
"reactionDate": "2015-10-21T07:26:10.731+0000",
"reportAlias": "feature-link",
"email": "recipient1@fullbounce.invalid",
"event": "5451f3b1e1c2485a5b71ca88",
"eventId": "56273dfbd4c6edc9107ec95c",
"mailingId": "5614e5e6d4c676adce44f1e8",
"sendDate": "2015-10-21T07:26:09.147+0000",
"sendingId": "56273e11d4c62cdd1be684f1",
"customerId": "customer_xyz",
"trackingHash": "hU9kL-FT0kCLA960"
},
{
"reactionType": "open",
"reactionDate": "2015-10-21T07:26:10.731+0000",
"reportAlias": "trackingpixel",
"email": "recipient1@fullbounce.invalid",
"event": "5451f3b1e1c2485a5b71ca88",
"eventId": "56273dfbd4c6edc9107ec95c",
"mailingId": "5614e5e6d4c676adce44f1e8",
"sendDate": "2015-10-21T07:26:09.147+0000",
"sendingId": "56273e11d4c62cdd1be684f1",
"customerId": "customer_xyz",
"trackingHash": "hU9kL-FT0kCLA960"
}
]
},
"_links": {
"first": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/reactions?page=0&size=200"
},
"last": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/reactions?page=29&size=200"
},
"next": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/reactions?page=1&size=200"
},
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/reactions"
}
},
"page": {
"number": 0,
"size": 200,
"totalElements": 5911,
"totalPages": 30
}
}200With anonymous tracking enabled reactions do not contain email, eventId, sendDate, sendingId and customerId.
Headers
Content-Type: application/jsonBody
{
"_embedded": {
"reactions": [
{
"reactionType": "click",
"reactionDate": "2015-10-21T07:26:10.731+0000",
"reportAlias": "feature-link",
"event": "5451f3b1e1c2485a5b71ca88",
"mailingId": "5614e5e6d4c676adce44f1e8",
"trackingHash": "hU9kL-FT0kCLA960"
},
{
"reactionType": "open",
"reactionDate": "2015-10-21T07:26:10.731+0000",
"reportAlias": "trackingpixel",
"event": "5451f3b1e1c2485a5b71ca88",
"mailingId": "5614e5e6d4c676adce44f1e8",
"trackingHash": "hU9kL-FT0kCLA960"
}
]
},
"_links": {
"first": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/reactions?page=0&size=200"
},
"last": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/reactions?page=29&size=200"
},
"next": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/reactions?page=1&size=200"
},
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/reactions"
}
},
"page": {
"number": 0,
"size": 200,
"totalElements": 5911,
"totalPages": 30
}
}400invalid filter parameters, like invalid begin and end dates, invalid reaction type
Body
{
"error": "Bad Request",
"exception": "com.inxmail.xcom.api.rest.InvalidDateParameter",
"message": "Start date 2015-10-24T11:20:14.887+0000 is in future",
"path": "/api-service/v1/reactions?begin=2015-10-24T11:20:14.887%2B0000",
"status": 400,
"timestamp": "2015-10-23T11:22:01.827+0000"
}Transaction Bounces ¶
Transaction BouncesGET/v1/bounces{?bounceType,event,eventId,sendingId,customerId,email,begin,end,page,size}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/bounces'
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/bounces?bounceType=hardbounce'
curl -u 'keyid:secret' --get --data-urlencode 'begin=2015-10-21T00:00:00.000Z' --data-urlencode 'end=2015-10-21T23:59:59.999Z' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/bounces'Get information about bounced emails that resulted from transactions.
The filtering parameters are all optional. If not specified, all bounces are returned. Only one of sendingId, customerId, email or eventId may be used. Other than that, filters can be combined, only bounces that match all criteria are returned.
The pagination parameters page and size should be used together, and apply within filtered results.
Example URI
- bounceType
enum(optional) Example: hardbouncefilters by the type of bounce as categorized by Inxmail Commerce
Choices:
hardbouncesoftbounce- event
string(optional) Example: 5451f3b1e1c2485a5b71ca88filters by the ID of the event type configuration
- eventId
string(optional) Example: 5534f2f3fcb24820d52f3413filters by the ID of a single transaction (as returned by /v1/events or /v1/eventsasmultipart)
- sendingId
string(optional) Example: 56273e12d4c62cdd1be68506filters by the ID of the sending of a mail (as included in an
eventStateentry in /v1/state/{id})- customerId
string(optional) Example: customer_xyzfilters by the customer ID that was specified in the event data
string(optional) Example: recipient@fullbounce.invalidfilters by the recipient email address (case insensitive, specify without personal part)
- begin
string(optional) Example: 2015-10-21T11:00:33.000Zfilters bounces starting from this timestamp, in ISO-8601 format
- end
string(optional) Example: 2015-10-21T11:00:33.000Zfilters bounces until this timestamp, in ISO-8601 format
- size
number(optional) Default: 200 Example: 200number of elements returned in a single response page (max. 500)
- page
number(optional) Default: 0 Example: 0result page number, if the request returns more results than the page size
200bounceType is one of:
-
softbounce- Softbounce. For further information see Softbounce -
hardbounce- Hardbounce. For further information see Hardbounce
Headers
Content-Type: application/jsonBody
{
"_embedded": {
"bounces": [
{
"bounceType": "hardbounce",
"bounceDate": "2015-10-21T07:26:10.731+0000",
"email": "recipient1@fullbounce.invalid",
"event": "5451f3b1e1c2485a5b71ca88",
"eventId": "56273dfbd4c6edc9107ec95c",
"mailingId": "5614e5e6d4c676adce44f1e8",
"sendDate": "2015-10-21T07:26:09.147+0000",
"sendingId": "56273e11d4c62cdd1be684f1",
"customerId": "customer_xyz"
},
{
"bounceType": "hardbounce",
"bounceDate": "2015-10-21T07:26:10.843+0000",
"email": "recipient2@fullbounce.invalid",
"event": "5451f3b1e1c2485a5b71ca88",
"eventId": "56273e08d4c6edc9107ec962",
"mailingId": "5614e5e6d4c676adce44f1e8",
"sendDate": "2015-10-21T07:26:10.370+0000",
"sendingId": "56273e12d4c62cdd1be68506"
}
]
},
"_links": {
"first": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/bounces?page=0&size=200"
},
"last": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/bounces?page=29&size=200"
},
"next": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/bounces?page=1&size=200"
},
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/bounces"
}
},
"page": {
"number": 0,
"size": 200,
"totalElements": 5911,
"totalPages": 30
}
}400invalid filter parameters, like invalid begin and end dates, invalid bounce type
Body
{
"error": "Bad Request",
"exception": "com.inxmail.xcom.api.rest.InvalidDateParameter",
"message": "Start date 2015-10-24T11:20:14.887+0000 is in future",
"path": "/api-service/v1/bounces?begin=2015-10-24T11:20:14.887%2B0000",
"status": 400,
"timestamp": "2015-10-23T11:22:01.827+0000"
}Transaction Complaints ¶
Transaction ComplaintsGET/v1/complaints{?complaintType,event,eventId,sendingId,customerId,email,begin,end,page,size}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/complaints'
curl -u 'keyid:secret' --get --data-urlencode 'begin=2015-10-21T00:00:00.000Z' --data-urlencode 'end=2015-10-21T23:59:59.999Z' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/complaints'Get information about complaints that resulted from transactions.
The filtering parameters are all optional. If not specified, all complaints are returned. Only one of sendingId, customerId, email or eventId may be used. Other than that, filters can be combined, only complaints that match all criteria are returned.
The pagination parameters page and size should be used together, and apply within filtered results.
Example URI
- complaintType
enum(optional) Example: feedbackloopfilters by the type of complaint
Choices:
feedbackloop- event
string(optional) Example: 5451f3b1e1c2485a5b71ca88filters by the ID of the event type configuration
- eventId
string(optional) Example: 5534f2f3fcb24820d52f3413filters by the ID of a single transaction (as returned by /v1/events or /v1/eventsasmultipart)
- sendingId
string(optional) Example: 56273e12d4c62cdd1be68506filters by the ID of the sending of a mail (as included in an
eventStateentry in /v1/state/{id})- customerId
string(optional) Example: customer_xyzfilters by the customer ID that was specified in the event data
string(optional) Example: recipient@fbl.invalidfilters by the recipient email address (case insensitive, specify without personal part)
- begin
string(optional) Example: 2015-10-21T11:00:33.000Zfilters complaints starting from this timestamp, in ISO-8601 format
- end
string(optional) Example: 2015-10-21T11:00:33.000Zfilters complaints until this timestamp, in ISO-8601 format
- size
number(optional) Default: 200 Example: 200number of elements returned in a single response page (max. 500)
- page
number(optional) Default: 0 Example: 0result page number, if the request returns more results than the page size
200complaintType is one of:
feedbackloop- FeedbackLoop. The recipient has marked the e-mail as spam.
Headers
Content-Type: application/jsonBody
{
"_embedded": {
"complaints": [
{
"complaintType": "feedbackloop",
"complaintDate": "2015-10-21T07:26:10.731+0000",
"email": "recipient1@fbl.invalid",
"event": "5451f3b1e1c2485a5b71ca88",
"eventId": "56273dfbd4c6edc9107ec95c",
"mailingId": "5614e5e6d4c676adce44f1e8",
"sendDate": "2015-10-21T07:26:09.147+0000",
"sendingId": "56273e11d4c62cdd1be684f1",
"customerId": "customer_xyz"
},
{
"complaintType": "feedbackloop",
"complaintDate": "2015-10-21T07:26:10.843+0000",
"email": "recipient2@fbl.invalid",
"event": "5451f3b1e1c2485a5b71ca88",
"eventId": "56273e08d4c6edc9107ec962",
"mailingId": "5614e5e6d4c676adce44f1e8",
"sendDate": "2015-10-21T07:26:10.370+0000",
"sendingId": "56273e12d4c62cdd1be68506"
}
]
},
"_links": {
"first": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/complaints?page=0&size=200"
},
"last": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/complaints?page=29&size=200"
},
"next": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/complaints?page=1&size=200"
},
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/complaints"
}
},
"page": {
"number": 0,
"size": 200,
"totalElements": 5911,
"totalPages": 30
}
}400invalid filter parameters, like invalid begin and end dates
Body
{
"error": "Bad Request",
"exception": "com.inxmail.xcom.api.rest.InvalidDateParameter",
"message": "Start date 2015-10-24T11:20:14.887+0000 is in future",
"path": "/api-service/v1/complaints?begin=2015-10-24T11:20:14.887%2B0000",
"status": 400,
"timestamp": "2015-10-23T11:22:01.827+0000"
}Blocklist ¶
The following resources supply information about email addresses that are blocked because emails hardbounced. Result sizes may be large, in that case the responses will contain only “pages” with a limited number of results.
Further pages can be retrieved by following the next (or previous) links. These links will contain the page and size request parameters as described below. For the initial request, these parameters are not required.
Blocklist ¶
BlocklistGET/v1/blocklist{?begin,end,page,size}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/blocklist'Get information about email addresses that are blocked because emails hardbounced. Returns an entry per email.
The filtering parameters are all optional. If not specified, all blocked email addreses are returned.
The pagination parameters page and size should be used together, and apply within filtered results.
Example URI
- begin
string(optional) Example: 2015-10-21T11:00:33.000Zfilters blocked addresses starting from this timestamp, in ISO-8601 format
- end
string(optional) Example: 2015-10-21T11:00:33.000Zfilters blocked addresses until this timestamp, in ISO-8601 format
- size
number(optional) Default: 200 Example: 200number of elements returned in a single response page (max. 500)
- page
number(optional) Default: 0 Example: 0result page number, if the request returns more results than the page size
200Value of blockType is:
hardbounce- Recipient was blocked due to hardbounce threshold
Headers
Content-Type: application/jsonBody
{
"_embedded": {
"blocklist": [
{
"email": "blocked1@domain.invalid",
"blockDate": "2015-10-21T07:26:09.147+0000",
"blockType": "hardbounce",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/blocklist/blocked1@domain.invalid"
},
}
},
{
"email": "blocked2@domain.invalid",
"blockDate": "2015-10-22T09:28:09.235+0000",
"blockType": "hardbounce",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/blocklist/blocked2@domain.invalid"
},
}
}
]
},
"_links": {
"first": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/blocklist?page=0&size=200"
},
"last": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/blocklist?page=29&size=200"
},
"next": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/blocklist?page=1&size=200"
},
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/blocklist"
}
},
"page": {
"number": 0,
"size": 200,
"totalElements": 5911,
"totalPages": 30
}
}400invalid filter parameters, like invalid begin and end dates
Body
{
"error": "Bad Request",
"exception": "com.inxmail.xcom.api.rest.InvalidDateParameter",
"message": "Start date 2015-10-24T11:20:14.887+0000 is in future",
"path": "/api-service/v1/blocklist?begin=2015-10-24T11:20:14.887%2B0000",
"status": 400,
"timestamp": "2015-10-23T11:22:01.827+0000"
}Single Blocked Email ¶
Single Blocked EmailGET/v1/blocklist/{email}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/blocklist/blocked@domain.invalid'Get information about a single email address that is blocked because it hardbounced.
Example URI
string(required) Example: blocked@domain.invalida single email address
200Value of blockType is:
hardbounce- Recipient was blocked due to hardbounce threshold
Headers
Content-Type: application/jsonBody
{
"email": "blocked@domain.invalid",
"blockDate": "2015-10-21T07:26:09.147+0000",
"blockType": "hardbounce",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/blocklist/blocked@domain.invalid"
}
}
}404A blocklist entry with this email does not exist
Body
{
"exception": "com.inxmail.xcom.api.blocklist.EmailNotFound",
"path": "/api-service/v1/blocklist/notinlist@domain.invalid",
"error": "Not Found",
"message": "Entry with email notinlist@domain.invalid not found",
"timestamp": "2016-01-11T09:03:21.080+0000",
"status": 404
}Remove Blocked Email ¶
Remove Blocked EmailDELETE/v1/blocklist/{email}
curl -u 'keyid:secret' -X DELETE 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/blocklist/blocked@domain.invalid'Remove a single email address from the blocklist.
Example URI
string(required) Example: blocked@domain.invalida single email address
200Headers
Content-Type: application/jsonBody
{
"email": "blocked@domain.invalid",
"blockType": "hardbounce",
"blockDate": "2015-10-21T07:26:09.147+0000",
}404A blocklist entry with this email does not exist
Body
{
"exception": "com.inxmail.xcom.api.blocklist.EmailNotFound",
"path": "/api-service/v1/blocklist/notinlist@domain.invalid",
"error": "Not Found",
"message": "Entry with email notinlist@domain.invalid not found",
"timestamp": "2016-01-11T09:03:21.080+0000",
"status": 404
}Blacklist ¶
The following resources supply information about email addresses that are explicitly denied to receive emails, usually on request of the adress’s owner.
Result sizes may be large, in that case the responses will contain only “pages” with a limited number of results.
Further pages can be retrieved by following the next (or previous) links. These links will contain the page and size request parameters as described below. For the initial request, these parameters are not required.
Blacklist ¶
BlacklistGET/v1/blacklist{?begin,end,page,size}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/blacklist'Get information about email addresses that are explicitly blacklisted. Returns an entry per email.
The filtering parameters are all optional. If not specified, all blocked email addreses are returned.
The pagination parameters page and size should be used together, and apply within filtered results.
Example URI
- begin
string(optional) Example: 2015-10-21T11:00:33.000Zfilters blocked addresses starting from this timestamp, in ISO-8601 format
- end
string(optional) Example: 2015-10-21T11:00:33.000Zfilters blocked addresses until this timestamp, in ISO-8601 format
- size
number(optional) Default: 200 Example: 200number of elements returned in a single response page (max. 500)
- page
number(optional) Default: 0 Example: 0result page number, if the request returns more results than the page size
200Value of blockType is:
explicit- Recipient was blocked due to manual blacklist entry
Headers
Content-Type: application/jsonBody
{
"_embedded": {
"blacklist": [
{
"email": "blocked1@domain.invalid",
"blockDate": "2015-10-21T07:26:09.147+0000",
"blockType": "explicit",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/blacklist/blocked1@domain.invalid"
},
}
},
{
"email": "blocked2@domain.invalid",
"blockDate": "2015-10-22T09:28:09.235+0000",
"blockType": "explicit",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/blacklist/blocked2@domain.invalid"
},
}
}
]
},
"_links": {
"first": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/blacklist?page=0&size=200"
},
"last": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/blacklist?page=29&size=200"
},
"next": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/blacklist?page=1&size=200"
},
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/blacklist"
}
},
"page": {
"number": 0,
"size": 200,
"totalElements": 5911,
"totalPages": 30
}
}400invalid filter parameters, like invalid begin and end dates
Body
{
"error": "Bad Request",
"exception": "com.inxmail.xcom.api.rest.InvalidDateParameter",
"message": "Start date 2015-10-24T11:20:14.887+0000 is in future",
"path": "/v1/blacklist?begin=2015-10-24T11:20:14.887%2B0000",
"status": 400,
"timestamp": "2015-10-23T11:22:01.827+0000"
}Single Blacklisted Email ¶
Single Blacklisted EmailGET/v1/blacklist/{email}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/blacklist/blocked@domain.invalid'Get information about a single email address that is blacklisted.
Example URI
string(required) Example: blocked@domain.invalida single email address
200Value of blockType is:
explicit- Recipient was blocked due to manual blacklist entry
Headers
Content-Type: application/jsonBody
{
"email": "blocked@domain.invalid",
"blockDate": "2015-10-21T07:26:09.147+0000",
"blockType": "explicit",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/blacklist/blocked@domain.invalid"
}
}
}404A blocklist entry with this email does not exist
Body
{
"exception": "com.inxmail.xcom.api.blocklist.EmailNotFound",
"path": "/v1/blacklist/notinlist@domain.invalid",
"error": "Not Found",
"message": "Entry with email notinlist@domain.invalid not found",
"timestamp": "2016-01-11T09:03:21.080+0000",
"status": 404
}Remove Email from Blacklist ¶
Remove Email from BlacklistDELETE/v1/blacklist/{email}
curl -u 'keyid:secret' -X DELETE 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/blacklist/blocked@domain.invalid'Remove a single email address from the blacklist.
Example URI
string(required) Example: blocked@domain.invalida single email address
200Headers
Content-Type: application/jsonBody
{
"email": "blocked@domain.invalid",
"blockType": "hardbounce",
"blockDate": "2015-10-21T07:26:09.147+0000",
}404A blocklist entry with this email does not exist
Body
{
"exception": "com.inxmail.xcom.api.blocklist.EmailNotFound",
"path": "/api-service/v1/blacklist/notinlist@domain.invalid",
"error": "Not Found",
"message": "Entry with email notinlist@domain.invalid not found",
"timestamp": "2016-01-11T09:03:21.080+0000",
"status": 404
}Add Email To Blacklist ¶
Add Email To BlacklistPOST/v1/blacklist
curl -X POST -u 'keyid:secret' -H 'Content-Type: application/json' -d '{"email":"toblock@domain.invalid"}' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/blacklist'Adds an email address explicitly to the blacklist. If the email address has already been blocked because of hardbounces, the entry is modified to an explicit blacklist entry. If the address has already been explicitly blocked, the entry is left unchanged. The resulting entry is returned.
Example URI
Body
{
"email": "toblock@domain.invalid"
}200Headers
Content-Type: application/jsonBody
{
"email": "toblock@domain.invalid",
"blockDate": "2016-01-21T07:26:09.147+0000",
"blockType": "explicit",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/blacklist/toblock@domain.invalid"
}
}
}400Invalid or missing email address.
Headers
Content-Type: application/jsonBody
{
"timestamp": "2016-02-01T10:25:57.184+0000",
"status": 400,
"error": "Bad Request",
"exception": "org.springframework.web.bind.MethodArgumentNotValidException",
"errors": [
{
"defaultMessage": "not a well-formed email address",
"objectName": "blocklistRequest",
"field": "email",
"rejectedValue": "toblock@domain@invalid",
"bindingFailure": false,
"code": "Email"
}
],
"message": "Validation failed for object='blocklistRequest'. Error count: 1",
"path": "/api-service/v1/blacklist"
}Send Raw Mail ¶
Send a complete email message ¶
Send a complete email messagePOST/v1/sendrawmail
Allows submitting an email message as an HTTP call instead of sending it by SMTP. The message must be a full message conforming to RFC 5322/2822,
encoded in Base64.
The recipient(s) must be defined as the message’s To: header.
For each additional To:, Cc:, Bcc: header a copy of the mail with a new unique relaySendingId will be sent.
For convenience and ease of use, a client development kit for the Java language is available at Inxmail Commerce API Client for Rawmail.
curl -X POST -u 'keyid:secret' -H 'Content-Type: application/json' -d '{"message":"YXNkZnNhZGZhc2Rm..."}' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/sendrawmail'Example URI
Body
{
"message": "YXNkZnNhZGZhc2Rm..."
}200If the email only contains one To: header and the email has been successfully submitted. This does not guarantee final delivery.
Body
{
"acceptedDate": "2016-10-20T12:37:07.299+0000",
"relaySendingId": "56273e11d4c62cdd1be684f1"
}200If the email contains additional To:, Cc:, Bcc: headers and the emails have been successfully submitted. This does not guarantee final delivery.
Body
{
"acceptedDate": "2016-10-20T12:37:07.299+0000",
"relaySendingId": "56273e11d4c62cdd1be684f1",
"recipientsWithSendingId": [
{
"recipient": "recipient@test.invalid",
"relaySendingId": "56273e11d4c62cdd1be684f1",
"type": "To"
},
{
"recipient": "cc@test.invalid",
"relaySendingId": "56273e11d4c62cdd1be695e3",
"type": "Cc"
},
{
"recipient": "bcc@test.invalid",
"relaySendingId": "56273e11d4c62cdd1be706d9",
"type": "Bcc"
}
]
}200If the email contains additional To:, Cc:, Bcc: headers and an additional email could not be successful submitted. This does not guarantee final delivery.
Body
{
"acceptedDate": "2016-10-20T12:37:07.299+0000",
"relaySendingId": "56273e11d4c62cdd1be684f1",
"recipientsWithSendingId": [
{
"recipient": "recipient@test.invalid",
"relaySendingId": "56273e11d4c62cdd1be684f1",
"type": "To"
},
{
"recipient": "cc@test.invalid",
"relaySendingId": "56273e11d4c62cdd1be695e3",
"type": "Cc"
},
{
"recipient": "bcc@test.invalid",
"type": "Bcc"
"error": "Send failed, because of an internal error"
}
]
}400Invalid or incomplete mime message, or invalid Base64 encoding
Headers
Content-Type: application/jsonBody
{
"exception": "org.springframework.mail.MailParseException",
"path": "/api-service/v1/sendrawmail",
"error": "Bad Request",
"message": "Incomplete MimeMessage; nested exception is jakarta.mail.MessagingException: Incomplete MimeMessage",
"timestamp": "2016-10-13T06:03:30.238+0000",
"status": 400
}413Attachment(s) exceeds allowed size
Headers
Content-Type: application/jsonBody
{
"timestamp" : 2016-10-20T12:37:07.299+0000,
"status" : 413,
"error" : "Payload Too Large",
"exception" : "com.inxmail.xcom.api.event.AttachmentToBig",
"message" : "Mail exceeds limit of 6291456."
}Mail Relay ¶
Mail Relay Sendings ¶
Mail Relay SendingsGET/v1/relaysendings{?email,correlationId1,correlationId2,correlationId3,begin,end,size,page}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/relaysendings'
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/relaysendings?email=recipient1@fullbounce.invalid'Get information about emails that are sent by the mail relay service. Returns an entry per single email.
Example URI
string(optional) Example: recipient@somewhere.invalidfilter by the recipient email address (case insensitive, specify without personal part)
- correlationId1
string(optional) Example: my-shop-identifierfilters sendings with correlationId1 matching given search string
- correlationId2
string(optional) Example: my-campaign-identifierfilters sendings with correlationId2 matching given search string
- correlationId3
string(optional) Example: my-mailing-identifierfilters sendings with correlationId3 matching given search string
- begin
string(optional) Example: 2015-10-21T11:00:33.000Zfilters sendings starting from this timestamp, in ISO-8601 format
- end
string(optional) Example: 2015-10-21T11:00:33.000Zfilters sendings until this timestamp, in ISO-8601 format
- size
number(optional) Default: 200 Example: 200number of elements returned in a single response page (max. 500)
- page
number(optional) Default: 0 Example: 0result page number, if the request returns more results than the page size
200Headers
Content-Type: application/jsonBody
{
"_embedded": {
"relaysendings": [
{
"relaySendingId": "56273e11d4c62cdd1be684f1",
"email": "recipient1@somewhere.invalid",
"sendDate": "2015-10-21T07:26:09.147+0000",
"correlationId1": "shop identifier",
"correlationId2": "campaign identifier",
"correlationId3": "mailing identifier",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relaysendings/56273e11d4c62cdd1be684f1"
}
}
},
{
"relaySendingId": "56273e11d4c62cdd1be681e3",
"email": "recipient2@somewhere.invalid",
"sendDate": "2015-10-21T07:26:13.243+0000",
"correlationId1": "shop identifier",
"correlationId2": "campaign identifier",
"correlationId3": "mailing identifier",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relaysendings/56273e11d4c62cdd1be681e3"
}
}
}
]
},
"_links": {
"first": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relaysendings?page=0&size=20"
},
"last": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relaysendings?page=1&size=20"
},
"next": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relaysendings?page=1&size=20"
},
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relaysendings"
}
},
"page": {
"number": 0,
"size": 200,
"totalElements": 5911,
"totalPages": 30
}
}400invalid filter parameters, like invalid begin and end dates
Body
{
"error": "Bad Request",
"exception": "com.inxmail.xcom.api.rest.InvalidDateParameter",
"message": "Start date 2015-10-24T11:20:14.887+0000 is in future",
"path": "/api-service/v1/relaysendings?begin=2015-10-24T11:20:14.887%2B0000",
"status": 400,
"timestamp": "2015-10-23T11:22:01.827+0000"
}Single Mail Relay Sending ¶
Single Mail Relay SendingGET/v1/relaysendings/{id}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/relaysendings/56273e11d4c62cdd1be684f1'Get information about a single sent mail relay email.
Example URI
- id
string(required) Example: 56273e11d4c62cdd1be684f1a single relay sending ID
200Headers
Content-Type: application/jsonBody
{
"relaySendingId": "56273e11d4c62cdd1be684f1",
"email": "recipient1@somewhere.invalid",
"sendDate": "2015-10-21T07:26:09.147+0000",
"correlationId1": "shop identifier",
"correlationId2": "campaign identifier",
"correlationId3": "mailing identifier",
"_links": {
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relaysendings/56273e11d4c62cdd1be684f1"
}
}
}400ID has an invalid format
Body
{
"exception": "org.springframework.core.convert.ConversionFailedException",
"path": "/api-service/v1/relaysendings/abc",
"error": "Bad Request",
"message": "Failed to convert from type [java.lang.String] to type [@org.springframework.web.bind.annotation.PathVariable org.bson.types.ObjectId] for value 'abc'; nested exception is java.lang.IllegalArgumentException: invalid hexadecimal representation of an ObjectId: [abc]",
"timestamp": "2023-02-16T12:53:01.731+00:00",
"status": 400
}404A sending with this ID does not exist
Body
{
"exception": "com.inxmail.xcom.api.sendinginfo.SendingNotFound",
"path": "/api-service/v1/relaysendings/5666b8bed4c6022b03786b72",
"error": "Not Found",
"message": "Sending with id 5666b8bed4c6022b03786b72 not found",
"timestamp": "2023-02-16T12:53:17.407+00:00",
"status": 404
}Mail Relay Reactions ¶
Mail Relay ReactionsGET/v1/relayreactions{?reactionType,email,relaySendingId,correlationId1,correlationId2,correlationId3,trackingHash,begin,end,size,page}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/relayreactions'
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/relayreactions?reactionType=open'Get information about recipient reactions (opened email, clicked link) from the mail relay service. Returns every single reaction as separate entry, i.e. one entry per individual click, even for multiple clicks of the same recipient on the same link.
The filtering parameters are all optional. If not specified, all reactions are returned.
The 3 different correlationIds contain the values defined and sent by your system as X-inx-correlationId1, X-inx-correlationId2, X-inx-correlationId3 headers in the mail message.
The pagination parameters page and size should be used together and apply within filtered results.
Example URI
- reactionType
enum(optional) Example: clickfilters by the type of reaction
Choices:
openclickstring(optional) Example: recipient@somewhere.invalidfilter by the recipient email address (case insensitive, specify without personal part)
- relaySendingId
string(optional) Example: 56273e12d4c62cdd1be68506filters by the ID of the relay sending of a mail
- correlationId1
string(optional) Example: my-shop-identifierfilters reactions with correlationId1 matching given search string
- correlationId2
string(optional) Example: my-campaign-identifierfilters reactions with correlationId2 matching given search string
- correlationId3
string(optional) Example: my-mailing-identifierfilters reactions with correlationId3 matching given search string
- trackingHash
string(optional) Example: hU9kL-FT0kCLA960filters by the tracking hash
- begin
string(optional) Example: 2015-10-21T11:00:33.000Zfilters reactions starting from this timestamp, in ISO-8601 format
- end
string(optional) Example: 2015-10-21T11:00:33.000Zfilters reactions until this timestamp, in ISO-8601 format
- size
number(optional) Default: 200 Example: 200number of elements returned in a single response page (max. 500)
- page
number(optional) Default: 0 Example: 0result page number, if the request returns more results than the page size
200reactionType is one of:
-
open- Mailing was opened by the recipient -
click- Link was clicked by the recipient
Headers
Content-Type: application/jsonBody
{
"_embedded": {
"relayreactions": [
{
"reactionType": "click",
"reactionDate": "2015-10-21T07:26:10.731+0000",
"url": "https://link1.example.invalid",
"email": "recipient1@somewhere.invalid",
"relaySendingId": "56273e11d4c62cdd1be684f1",
"sendDate": "2015-10-21T07:26:09.147+0000",
"correlationId1": "shop identifier",
"correlationId2": "campaign identifier",
"correlationId3": "mailing identifier",
"trackingHash": "hU9kL-FT0kCLA960"
},
{
"reactionType": "open",
"reactionDate": "2015-10-21T07:26:10.731+0000",
"url": "https://www.example.invalid/trackingpixel.png",
"email": "recipient1@somewhere.invalid",
"relaySendingId": "56273e11d4c62cdd1be684f1",
"sendDate": "2015-10-21T07:26:09.147+0000",
"correlationId1": "shop identifier",
"correlationId2": "campaign identifier",
"correlationId3": "mailing identifier",
"trackingHash": "hU9kL-FT0kCLA960"
}
]
},
"_links": {
"first": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relayreactions?page=0&size=20"
},
"last": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relayreactions?page=1&size=20"
},
"next": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relayreactions?page=1&size=20"
},
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relayreactions"
}
},
"page": {
"number": 0,
"size": 200,
"totalElements": 5911,
"totalPages": 30
}
}400invalid filter parameters, like invalid begin and end dates, invalid reaction type
Body
{
"error": "Bad Request",
"exception": "com.inxmail.xcom.api.rest.InvalidDateParameter",
"message": "Start date 2015-10-24T11:20:14.887+0000 is in future",
"path": "/api-service/v1/relayreactions?begin=2015-10-24T11:20:14.887%2B0000",
"status": 400,
"timestamp": "2015-10-23T11:22:01.827+0000"
}Mail Relay Bounces ¶
Mail Relay BouncesGET/v1/relaybounces{?bounceType,correlationId1,correlationId2,correlationId3,begin,end,page,size}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/relaybounces'Get information about bounced emails from the mail relay service.
The filtering parameters are all optional. If not specified, all bounces are returned. Filters can be combined, only bounces that match all criteria are returned.
The 3 different correlationIds contain the values defined and sent by your system as X-inx-correlationId1, X-inx-correlationId2, X-inx-correlationId3 headers in the mail message.
The pagination parameters page and size should be used together and apply within filtered results.
Example URI
- bounceType
enum(optional) Example: hardbouncefilters by the type of bounce as categorized by Inxmail Commerce
Choices:
hardbouncesoftbounce- correlationId1
string(optional) Example: my-shop-identifierfilters bounces with correlationId1 matching given search string
- correlationId2
string(optional) Example: my-campaign-identifierfilters bounces with correlationId2 matching given search string
- correlationId3
string(optional) Example: my-mailing-identifierfilters bounces with correlationId3 matching given search string
- begin
string(optional) Example: 2015-10-21T11:00:33.000Zfilters bounces starting from this timestamp, in ISO-8601 format
- end
string(optional) Example: 2015-10-21T11:00:33.000Zfilters bounces until this timestamp, in ISO-8601 format
string(optional) Example: recipient@somewhere.invalidfilter by the recipient email address (case insensitive, specify without personal part)
- relaySendingId
string(optional) Example: 56273e12d4c62cdd1be68506filters by the ID of the relay sending of a mail
- size
number(optional) Default: 200 Example: 200number of bounce elements returned in a single response page (max. 500)
- page
number(optional) Default: 0 Example: 0result page number, if the request returns more results than the page size
200bounceType is one of:
-
softbounce- Softbounce. For further information see Softbounce -
hardbounce- Hardbounce. For further information see Hardbounce
Headers
Content-Type: application/jsonBody
{
"_embedded": {
"relayBounces": [
{
"bounceType": "hardbounce",
"bounceDate": "2015-09-23T11:02:09.409+0000",
"email": "test30@test.invalid",
"relaySendingId": "562a13b1d4c696d88b90a681",
"sendDate": "2015-10-23T11:02:09.409+0000",
"correlationId1": "shop identifier",
"correlationId2": "campaign identifier",
"correlationId3": "mailing identifier"
},
{
"bounceType": "hardbounce",
"bounceDate": "2015-09-24T11:02:09.403+0000",
"email": "test29@test.invalid",
"relaySendingId": "562a13b1d4c696d88b90a67f",
"sendDate": "2015-10-23T11:02:09.403+0000",
"correlationId1": "shop identifier",
"correlationId2": "campaign identifier",
"correlationId3": "mailing identifier"
}
]
},
"_links": {
"first": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relaybounces?page=0&size=20"
},
"last": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relaybounces?page=1&size=20"
},
"next": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relaybounces?page=1&size=20"
},
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relaybounces"
}
},
"page": {
"number": 0,
"size": 20,
"totalElements": 30,
"totalPages": 2
}
}400invalid filter parameters, like invalid begin and end dates, invalid bounce type
Body
{
"error": "Bad Request",
"exception": "com.inxmail.xcom.api.rest.InvalidDateParameter",
"message": "Start date 2015-10-24T11:20:14.887+0000 is in future",
"path": "/api-service/v1/relaybounces?begin=2015-10-24T11:20:14.887%2B0000",
"status": 400,
"timestamp": "2015-10-23T11:22:01.827+0000"
}Mail Relay Complaints ¶
Mail Relay ComplaintsGET/v1/relaycomplaints{?complaintType,correlationId1,correlationId2,correlationId3,begin,end,page,size}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/relaycomplaints'Get information about complaints from the mail relay service.
The filtering parameters are all optional. If not specified, all complaints are returned. Filters can be combined, only complaints that match all criteria are returned.
The 3 different correlationIds contain the values defined and sent by your system as X-inx-correlationId1, X-inx-correlationId2, X-inx-correlationId3 headers in the mail message.
The pagination parameters page and size should be used together and apply within filtered results.
Example URI
- complaintType
enum(optional) Example: feedbackloopfilters by the type of complaint
Choices:
feedbackloop- correlationId1
string(optional) Example: my-shop-identifierfilters complaints with correlationId1 matching given search string
- correlationId2
string(optional) Example: my-campaign-identifierfilters complaints with correlationId2 matching given search string
- correlationId3
string(optional) Example: my-mailing-identifierfilters complaints with correlationId3 matching given search string
- begin
string(optional) Example: 2015-10-21T11:00:33.000Zfilters complaints starting from this timestamp, in ISO-8601 format
- end
string(optional) Example: 2015-10-21T11:00:33.000Zfilters complaints until this timestamp, in ISO-8601 format
string(optional) Example: recipient@somewhere.invalidfilter by the recipient email address (case insensitive, specify without personal part)
- relaySendingId
string(optional) Example: 56273e12d4c62cdd1be68506filters by the ID of the relay sending of a mail
- size
number(optional) Default: 200 Example: 200number of complaint elements returned in a single response page (max. 500)
- page
number(optional) Default: 0 Example: 0result page number, if the request returns more results than the page size
200complaintType is one of:
feedbackloop- Feedbackloop. The recipient has marked the e-mail as spam.
Headers
Content-Type: application/jsonBody
{
"_embedded": {
"relayComplaints": [
{
"complaintType": "feedbackloop",
"complaintDate": "2015-09-23T11:02:09.409+0000",
"email": "test30@test.invalid",
"relaySendingId": "562a13b1d4c696d88b90a681",
"sendDate": "2015-10-23T11:02:09.409+0000",
"correlationId1": "shop identifier",
"correlationId2": "campaign identifier",
"correlationId3": "mailing identifier"
},
{
"complaintType": "feedbackloop",
"complaintDate": "2015-09-24T11:02:09.403+0000",
"email": "test29@test.invalid",
"relaySendingId": "562a13b1d4c696d88b90a67f",
"sendDate": "2015-10-23T11:02:09.403+0000",
"correlationId1": "shop identifier",
"correlationId2": "campaign identifier",
"correlationId3": "mailing identifier"
}
]
},
"_links": {
"first": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relaycomplaints?page=0&size=20"
},
"last": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relaycomplaints?page=1&size=20"
},
"next": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relaycomplaints?page=1&size=20"
},
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/relaycomplaints"
}
},
"page": {
"number": 0,
"size": 20,
"totalElements": 30,
"totalPages": 2
}
}400invalid filter parameters, like invalid begin and end dates, invalid complaint type
Body
{
"error": "Bad Request",
"exception": "com.inxmail.xcom.api.rest.InvalidDateParameter",
"message": "Start date 2015-10-24T11:20:14.887+0000 is in future",
"path": "/api-service/v1/relaycomplaints?begin=2015-10-24T11:20:14.887%2B0000",
"status": 400,
"timestamp": "2015-10-23T11:22:01.827+0000"
}Delivery ¶
The following resources supply information about mail delivery state. Result sizes may be large, in that case the responses will contain only “pages” with a limited number of results.
Further pages can be retrieved by following the next (or previous) links. These links will contain the page and size request parameters as described below. For the initial request, these parameters are not required.
Delivery information is available for 30 days after delivery and will be deleted afterwards.
Deliveries ¶
DeliveriesGET/v1/deliveries{?sendingId,sendingType,email,status,begin,end,page,size}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/deliveries'
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/deliveries?status=sent'The filtering parameters are all optional. If not specified, all deliveries are returned.
The pagination parameters page and size should be used together, and apply within filtered results.
Example URI
- sendingId
string(optional) Example: 5534f2f3fcb24820d52f3413filters by the ID of a sending
- sendingType
string(optional) Example: `event`, `relay` or `test`,filter by the sending type (
eventfortransaction sending,relayformail relay sendings,testfortest sendings)string(optional) Example: recipient@company.invalidfilters by the recipient email address
- status
string(optional) Example: sentfilters by the state
- begin
string(optional) Example: 2015-10-21T11:00:33.000Zfilters deliveries starting from this timestamp, in ISO-8601 format
- end
string(optional) Example: 2015-10-21T11:00:33.000Zfilters deliveries until this timestamp, in ISO-8601 format
- size
number(optional) Default: 200 Example: 200number of elements returned in a single response page (max. 500)
- page
number(optional) Default: 0 Example: 0result page number, if the request returns more results than the page size
200sendingType is one of:
-
event- Sending relates to a event mail sendout -
relay- Sending relates to a mail relay sendout -
event- Sending relates to a event mail sendout
status is one of:
-
sent- Email was delivered to the target host -
bounced- Email was not delivered. Target host permanently rejected the delivery attempt -
deferred- Delivery was deferred. Target host temporarily refused the delivery attempt -
rejected- Mail server directly rejected the email. Delivery to target host was not attempted.
Headers
Content-Type: application/jsonBody
{
"_embedded": {
"deliveries": [
{
"deliveryId": "mx01-out-3qbBbW4wRhz1Sc",
"sendingId": "546c9f93e1c2abf2ddfc2cc2",
"sendingType": "test",
"sendouts": [
{
"deliveryDate": "2016-03-31T04:38:32.000+0000",
"email": "recipient@company.invalid",
"targetHost": "mx01.xcom.dmz.invalid",
"targetIp": "172.23.16.22",
"dsnMessage": "(250 2.0.0 Ok: queued as 3qbBbX1HDjz7rYc)",
"dsnCode": "2.0.0",
"status": "sent"
}
]
},
{
"deliveryId": "mx01-out-3qbBcD1091z1Sc",
"sendingId": "551a9f13e1c2abf2ddfc2cd1",
"sendingtype": "relay",
"sendouts": [
{
"deliveryDate": "2016-03-31T04:39:08.000+0000",
"email": "test@company.invalid",
"targetHost": "mx01.xcom.dmz.invalid",
"targetIp": "172.23.16.22",
"dsnMessage": "(250 2.0.0 Ok: queued as 3qbBcD1zGFz7sC5)",
"dsnCode": "2.0.0",
"status": "sent"
},
{
"deliveryDate": "2016-03-31T04:39:08.000+0000",
"email": "archive@archive.invalid",
"targetHost": "mx01.archive.invalid",
"targetIp": "192.24.17.23",
"dsnMessage": "(250 2.0.0 Ok: queued as 3q42GD1zGFz7sC5)",
"dsnCode": "4.0.0",
"status": "deferred"
}
]
}
]
},
"_links": {
"first": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/deliveries?page=0&size=200"
},
"last": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/deliveries?page=29&size=200"
},
"next": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/deliveries?page=1&size=200"
},
"self": {
"href": "https://spaceid.api.inxmail-commerce.com/api-service/v1/deliveries"
}
},
"page": {
"number": 0,
"size": 200,
"totalElements": 5911,
"totalPages": 30
}
}400invalid filter parameters, like invalid begin and end dates, invalid reaction type
Body
{
"error": "Bad Request",
"exception": "com.inxmail.xcom.api.rest.InvalidDateParameter",
"message": "Start date 2015-10-24T11:20:14.887+0000 is in future",
"path": "/api-service/v1/deliveries?begin=2015-10-24T11:20:14.887%2B0000",
"status": 400,
"timestamp": "2015-10-23T11:22:01.827+0000"
}Errorlog ¶
The following resource provides information about errorlogs. An errorlog is written when an error occurs, which is caused by the user or the system.
Single Errorlog ¶
Single ErrorlogGET/v1/errorlogs/{id}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/errorlogs/56273e12d4c62cdd1be68506'Get information about a single errorlog.
Example URI
- id
string(required) Example: 56273e12d4c62cdd1be68506a single errorlog ID
200Headers
Content-Type: application/jsonBody
{
"id": "63b905da3ab87d67437acc2a",
"level": "ERROR",
"error": "Recipient email address must be a valid email address",
"detail": "{Model={CustomerGender=female, CompanyName=null, CustomerFirstName=Margrit, CustomerEmail=Margrit.Hauger@t.-online.deqw, CustomerLastName=Hauger, ActivationLinkUrl=https://accounts.dm.de/activation?customerid=102134625&token=285b64d9-d41c-4e0c-b2a5-76fd6d660974&contactsource=09757, CustomerId=102134625}}",
"errorCode": "INX_1110",
"eventTypeId": "UserAccountActivation",
"campaignId": "5885cf786c459144a87e52f0",
"mailingId": null,
"errorTime": "2023-01-07T05:40:42.347+0000",
"isRead": false,
"_links": {
"self": {
"href": "http://dm-services.api.localhost:10080/api-service/v1/errorlogs/63b905da3ab87d67437acc2a"
}
}
}400ID has an invalid format
Body
{
"error": "Bad Request",
"exception": "org.springframework.web.method.annotation.MethodArgumentTypeMismatchException",
"message": "Failed to convert value of type 'java.lang.String' to required type 'org.bson.types.ObjectId'; nested exception is org.springframework.core.convert.ConversionFailedException: Failed to convert from type java.lang.String to type @org.springframework.web.bind.annotation.PathVariable org.bson.types.ObjectId for value 'abc'; nested exception is java.lang.IllegalArgumentException: invalid ObjectId [abc]",
"path": "/v1/errorlogs/abc",
"status": 400,
"timestamp": "2023-02-14T08:03:17.266+00:00"
}404A errorlog with ID does not exist
Body
{
"error": "Not Found",
"exception": "com.inxmail.xcom.api.errorlog.ErrorLogNotFound",
"message": "ErrorLog with id: 63b905da3ab87d67437acc20 not found",
"path": "/api-service/v1/errorlogs/63b905da3ab87d67437acc20",
"status": 404,
"timestamp": "2023-02-14T08:39:11.757+00:00"
}Errorlogs ¶
ErrorlogsGET/v1/errorlogs{?isRead,mailingId,campaignId,eventTypeId,begin,end,page}
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/errorlogs'
curl -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/errorlogs?errorLevel=ERROR'Get information about errorlogs that are available.
The filtering parameters are all optional. If not specified, all reactions are returned.
The pagination parameters page and size should be used together, and apply within filtered results.
Example URI
- errorLevel
enum(optional) Example: 'ErrorLevel'filter by the ErrorLevel.
Choices:
'ERROR''WARN''INFO'- isRead
boolean(optional)filters according to the read condition.
- ErrorCode
string(optional)filters according to the error code that describes the type of the error.
- mailingId
string(optional)filters by the mailing id associated with the error.
- campaignId
string(optional)filters by the campaign id associated with the error.
- eventTypeId
string(optional)filters by the event type id associated with the error.
- begin
string(optional) Example: 2015-10-21T11:00:33.000Zfilters errorlogs starting from this timestamp, in ISO-8601 format
- end
string(optional) Example: 2015-10-21T11:00:33.000Zfilters errorlogs until this timestamp, in ISO-8601 format
- page
number(optional) Example: 0result page number, if the request returns more results than the page size + Default: 0
200Headers
Content-Type: application/jsonBody
{
"_embedded": {
"errorlogs": [
{
"errorLogId": "63b905da3ab87d67437acc2a",
"level": "ERROR",
"error": "Recipient email address must be a valid email address",
"detail": "{Model={CustomerGender=female, CompanyName=null, CustomerFirstName=Erika, CustomerEmail=erika.musterfrau@invalid.de, CustomerLastName=Musterfrau, ActivationLinkUrl=https://someLink.de, CustomerId=102134621}}",
"errorCode": "INX_1110",
"eventTypeId": "UserAccountActivation",
"campaignId": "5885cf786c459144a87e52f0",
"mailingId": null,
"errorTime": "2023-01-07T05:40:42.347+0000",
"isRead": false,
"_links": {
"self": {
"href": "http://spaceid.api.inxmail-commerce.com/api-servicev1/v1/errorlogs/63b905da3ab87d67437acc2a"
}
}
},
{
"errorLogId": "63b8f8ba3525b0639e25372a",
"level": "ERROR",
"error": "Recipient email address must be a valid email address",
"detail": "{Model={CustomerGender=male, CompanyName=null, CustomerFirstName=Max, CustomerEmail=max.mustermann@invalid.de, CustomerLastName=Mustermann, ActivationLinkUrl=https://someLink.de, CustomerId=102134631}}",
"errorCode": "INX_1110",
"eventTypeId": "UserAccountActivation",
"campaignId": "5885cf786c459144a87e52f0",
"mailingId": null,
"errorTime": "2023-01-07T04:44:42.178+0000",
"isRead": false,
"_links": {
"self": {
"href": "http://spaceid.api.inxmail-commerce.com/api-servicev1/v1/errorlogs/63b8f8ba3525b0639e25372a"
}
}
}
]
},
"_links": {
"self": {
"href": "http://spaceid.api.inxmail-commerce.com/api-service/v1/errorlogs"
},
"first": {
"href": "http://spaceid.api.inxmail-commerce.com/api-servicev1/errorlogs?page=0&size=200"
},
"next": {
"href": "http://spaceid.api.inxmail-commerce.com/api-servicev1/errorlogs?page=1&size=200"
},
"last": {
"href": "http://spaceid.api.inxmail-commerce.com/api-service/v1/errorlogs?page=3&size=200"
}
},
"page": {
"size": 200,
"totalElements": 661,
"totalPages": 4,
"number": 0
}
}400Body
invalid filter parameters, like invalid begin and end dates, invalid reaction type
+ Body
{
"error": "Bad Request",
"exception": "com.inxmail.xcom.api.rest.InvalidDateParameter",
"message": "Start date 2015-10-24T11:20:14.887+0000 is in future",
"path": "/v1/errorlogs?begin=2015-10-24T11:20:14.887%2B0000",
"status": 400,
"timestamp": "2015-10-23T11:22:01.827+0000"
}Mark Single Errorlog as read ¶
Mark Single Errorlog as readPOST/v1/errorlogs/{id}/mark
curl -X POST -u 'keyid:secret' -H 'Content-Type: application/json' -d '{"isRead":true}' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/errorlogs/56273e12d4c62cdd1be68506/mark'Edit read status for a single errorlog entry.
Example URI
- id
string(required) Example: 56273e12d4c62cdd1be68506a single errorlog ID
200Headers
Content-Type: application/jsonBody
{
"id": "56273e12d4c62cdd1be68506",
"level": "ERROR",
"error": "Recipient email address must be a valid email address",
"detail": "{Model={CustomerGender=female, CompanyName=null, CustomerFirstName=Margrit, CustomerEmail=Margrit.Hauger@t.-online.deqw, CustomerLastName=Hauger, ActivationLinkUrl=https://accounts.dm.de/activation?customerid=102134625&token=285b64d9-d41c-4e0c-b2a5-76fd6d660974&contactsource=09757, CustomerId=102134625}}",
"errorCode": "INX_1110",
"eventTypeId": "UserAccountActivation",
"campaignId": "5885cf786c459144a87e52f0",
"mailingId": null,
"errorTime": "2023-01-07T05:40:42.347+0000",
"isRead": true,
"_links": {
"self": {
"href": "http://dm-services.api.localhost:10080/api-service/v1/errorlogs/56273e12d4c62cdd1be68506"
}
}
}400ID has an invalid format
Body
{
"error": "Bad Request",
"exception": "org.springframework.web.method.annotation.MethodArgumentTypeMismatchException",
"message": "Failed to convert value of type 'java.lang.String' to required type 'org.bson.types.ObjectId'; nested exception is org.springframework.core.convert.ConversionFailedException: Failed to convert from type java.lang.String to type @org.springframework.web.bind.annotation.PathVariable org.bson.types.ObjectId for value 'abc'; nested exception is java.lang.IllegalArgumentException: invalid ObjectId [abc]",
"path": "/v1/errorlogs/abc",
"status": 400,
"timestamp": "2023-02-14T08:03:17.266+00:00"
}404A errorlog with ID does not exist
Body
{
"error": "Not Found",
"exception": "com.inxmail.xcom.api.errorlog.ErrorLogNotFound",
"message": "ErrorLog with id: 63b905da3ab87d67437acc20 not found",
"path": "/api-service/v1/errorlogs/63b905da3ab87d67437acc20",
"status": 404,
"timestamp": "2023-02-14T08:39:11.757+00:00"
}Edit read status for all Errorlog entries ¶
Edit read status for all Errorlog entriesPOST/v1/errorlogs/mark
curl -X POST -u 'keyid:secret' 'https://{spaceid}.api.inxmail-commerce.com/api-service/v1/errorlogs/mark?isRead=true'Edit read status for all errorlog entries.
The parameter isRead must be specified.
Example URI
- isRead
boolean(required) Example: trueedits the mark status for all errorlog entries to the specific value.
200Headers
Content-Type: application/jsonBody
{
"success": true,
"updateCount": 12345
}