Back to top

Inxmail Commerce API

Inxmail Commerce API allows you to trigger transaction event workflows and retrieve information about the outcomes of these transactions.

Authentication

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 Requests
GET/

All requests are scoped to a single Inxmail Commerce space. The space ID is specified as first part of the domain name.

Example URI

GET https://{spaceid}.api.inxmail-commerce.com/api-service/
URI Parameters
HideShow
spaceid
string (required) Example: a-space

ID of the Inxmail Commerce space

Response  404
HideShow

Space 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 Point
GET/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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1
Response  200
HideShow
Body
{
  "_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 Event
POST/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”, “timestamp”, “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

POST https://{spaceid}.api.inxmail-commerce.com/api-service/v1/events
Request  Example with attachments
HideShow
Body
{
  "event": "neworder",
  "timestamp": "2015-01-27T10:25:43.511Z",
  "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"
    }
  ]
}
Request  Example with embedded images
HideShow
Body
{
  "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"
        }
      }
    ]
  }
}
Request  Example with transaction identifier
HideShow
Body
{
  "event": "neworder",
  "transactionId": "1234",
  "timestamp": "2015-01-27T10:25:43.511Z",
  "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"
      }
    ]
  }
}
Response  200
HideShow

Request 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"
    }
  }
}
Response  400
HideShow

Invalid or incomplete request body or invalid attachments

Headers
Content-Type: application/json
Body
{
  "timestamp": 1423553419221,
  "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": "/v1/events/"
}
Response  409
HideShow

Repeated submission for same transaction

Headers
Content-Type: application/json
Body
{
  "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"
}
Response  413
HideShow

Attachment(s) exceeds allowed size

Headers
Content-Type: application/json
Body
{
  "timestamp": 1423553419221,
  "status": 413,
  "error": "Payload Too Large",
  "exception": "com.inxmail.xcom.api.event.AttachmentToBig",
  "message": "File exceeds limit of 6291456."
}
Response  500
HideShow

Technical error while processing the request. The same request may succeed at other times.

Headers
Content-Type: application/json
Body
{
  "timestamp": 1423554303529,
  "status": 500,
  "error": "Internal Server Error",
  "exception": "java.lang.RuntimeException",
  "message": "java.io.IOException: IO ERROR",
  "path": "/v1/events/"
}

Trigger Event as Multipart

Trigger Event as Multipart
POST/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

POST https://{spaceid}.api.inxmail-commerce.com/api-service/v1/eventsasmultipart
Request
HideShow
Headers
Content-Type: multipart/mixed, boundary=AaB03x
Body
--AaB03x
Content-Disposition: form-data; name="event"
Content-Type: application/json

{
    "event" : "neworder",
    "timestamp" : "2015-01-27T10:25:43.511Z",
    "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--
Response  200
HideShow

Request 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"
    }
  }
}
Response  400
HideShow

Invalid or incomplete request body (json eventdata)

Headers
Content-Type: application/json
Body
{
  "timestamp": 1423553419221,
  "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": "/v1/eventsasmultipart/"
}
Response  409
HideShow

Repeated submission for same transaction

Headers
Content-Type: application/json
Body
{
  "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"
}
Response  413
HideShow

Attachment(s) exceeds allowed size

Headers
Content-Type: application/json
Body
{
  "timestamp": 1423553419221,
  "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)"
}
Response  500
HideShow

Technical error while processing the request. The same request may succeed at other times.

Headers
Content-Type: application/json
Body
{
  "timestamp": 1423554303529,
  "status": 500,
  "error": "Internal Server Error",
  "exception": "java.lang.RuntimeException",
  "message": "java.io.IOException: IO ERROR",
  "path": "/v1/eventsasmultipart/"
}

Request Event State

Request Event State
GET/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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/state/55d6c48b3004b15caffc0f15
URI Parameters
HideShow
id
string (required) Example: 55d6c48b3004b15caffc0f15

transaction ID for which the state should be returned, the transaction ID is returned in the result of a /v1/event or /v1/eventsasmultipart request

Response  200
HideShow

The 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"
    }
  }
}
Response  400
HideShow

id in wrong format

Body
{
  "timestamp": "2015-08-21T06:08:39.236+0000",
  "status": 400,
  "error": "Bad Request",
  "exception": "org.springframework.beans.TypeMismatchException",
  "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.RequestParam org.bson.types.ObjectId for value ''; nested exception is java.lang.IllegalArgumentException: invalid ObjectId []",
  "path": "/v1/state"
}
Response  404
HideShow

transaction with this id does not exist

Body
{
  "timestamp": "2015-08-21T06:04:02.306+0000",
  "status": 404,
  "error": "Not Found",
  "exception": "com.inxmail.xcom.api.state.EventStateController$EventDataNotFoundException",
  "message": "id not found",
  "path": "/v1/state"
}

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

Eventtypes
GET/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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/eventtypes
URI Parameters
HideShow
name
string (optional) Example: EventIdentifier

filters by the EventIdentifier used to trigger events for this eventtype.

size
number (optional) Default: 200 Example: 200

number of elements returned in a single response page (max. 500)

page
number (optional) Default: 0 Example: 0

result page number, if the request returns more results than the page size

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "_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 Eventtype
GET/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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/eventtypes/5812e8d130049f950f8e3fb5
URI Parameters
HideShow
eventTypeId
string (required) Example: 5812e8d130049f950f8e3fb5

a single eventTypeId

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "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"
    }
  }
}
Response  400
HideShow

ID 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/eventtypes/abc",
  "status": 400,
  "timestamp": "2015-12-08T11:08:19.203+0000"
}
Response  404
HideShow

A eventType with this ID does not exist

Body
{
  "exception": "com.inxmail.xcom.api.event.EventTypeNotFound",
  "path": "/v1/eventtypes/5812f02d3004ff59a860e585",
  "error": "Not Found",
  "message": "EventType with id 5812f02d3004ff59a860e585 not found",
  "timestamp": "2016-10-28T06:29:01.616+0000",
  "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

Sendings
GET/v1/sendings{?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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/sendings?eventId=5534f2f3fcb24820d52f3413&customerId=customer_xyz&email=recipient@fullbounce.invalid&begin=2015-10-21T11:00:33.000+0000&end=2015-10-21T11:00:33.000+0000&page=0&size=200
URI Parameters
HideShow
eventId
string (optional) Example: 5534f2f3fcb24820d52f3413

filters by the ID of a single transaction (as returned by /v1/event or /v1/eventsasmultipart)

customerId
string (optional) Example: customer_xyz

filter by the customer ID that was specified in the event data

email
string (optional) Example: recipient@fullbounce.invalid

filters by the recipient email address (case insensitive, specify without personal part)

begin
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters sendings starting from this timestamp, in ISO-8601 format

end
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters sendings until this timestamp, in ISO-8601 format

size
number (optional) Default: 200 Example: 200

number of elements returned in a single response page (max. 500)

page
number (optional) Default: 0 Example: 0

result page number, if the request returns more results than the page size

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "_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
    }
}
Response  400
HideShow

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/sendings?begin=2015-10-24T11:20:14.887%2B0000",
  "status": 400,
  "timestamp": "2015-10-23T11:22:01.827+0000"
}

Single Sending

Single Sending
GET/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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/sendings/56273e12d4c62cdd1be68506
URI Parameters
HideShow
id
string (required) Example: 56273e12d4c62cdd1be68506

a single sending ID (as included in an eventState entry in /v1/state/{id})

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "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"
    }
  }
}
Response  400
HideShow

ID 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/sendings/abc",
  "status": 400,
  "timestamp": "2015-12-08T11:08:19.203+0000"
}
Response  404
HideShow

A sending with this ID does not exist

Body
{
  "error": "Not Found",
  "exception": "com.inxmail.xcom.api.sendinginfo.SendingNotFound",
  "message": "Sending with id 5666b8bed4c6022b03786b72 not found",
  "path": "/v1/sendings/5666b8bed4c6022b03786b72",
  "status": 404,
  "timestamp": "2015-12-08T11:02:22.916+0000"
}

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 Reactions
GET/v1/reactions{?reactionType,eventId,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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/reactions?reactionType=click&eventId=5534f2f3fcb24820d52f3413&sendingId=56273e12d4c62cdd1be68506&customerId=customer_xyz&email=recipient@fullbounce.invalid&begin=2015-10-21T11:00:33.000+0000&end=2015-10-21T11:00:33.000+0000&page=0&size=200&trackingHash=hU9kL-FT0kCLA960
URI Parameters
HideShow
reactionType
enum (optional) Example: click

filters by the type of reaction

Choices: open click

eventId
string (optional) Example: 5534f2f3fcb24820d52f3413

filters by the ID of a single transaction (as returned by /v1/event or /v1/eventsasmultipart)

sendingId
string (optional) Example: 56273e12d4c62cdd1be68506

filters by the ID of the sending of a mail (as included in an eventState entry in /v1/state/{id})

customerId
string (optional) Example: customer_xyz

filter by the customer ID that was specified in the event data

email
string (optional) Example: recipient@fullbounce.invalid

filter by the recipient email address (case insensitive, specify without personal part)

begin
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters reactions starting from this timestamp, in ISO-8601 format

end
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters reactions until this timestamp, in ISO-8601 format

trackingHash
string (optional) Example: hU9kL-FT0kCLA960

filters by the tracking hash

size
number (optional) Default: 200 Example: 200

number of elements returned in a single response page (max. 500)

page
number (optional) Default: 0 Example: 0

result page number, if the request returns more results than the page size

Response  200
HideShow

reactionType is one of:

  • open - Mailing was opened by the recipient

  • click - Link was clicked by the recipient

Headers
Content-Type: application/json
Body
{
  "_embedded": {
    "reactions": [
      {
        "reactionType": "click",
        "reactionDate": "2015-10-21T07:26:10.731+0000",
        "reportAlias": "feature-link",
        "email": "recipient1@fullbounce.invalid",
        "eventId": "56273dfbd4c6edc9107ec95c",
        "sendDate": "2015-10-21T07:26:09.147+0000",
        "sendingId": "56273e11d4c62cdd1be684f1",
        "customerId": "customer_xyz",
        "event": "5451f3b1e1c2485a5b71ca88",
        "trackingHash": "hU9kL-FT0kCLA960"
      },
      {
        "reactionType": "open",
        "reactionDate": "2015-10-21T07:26:10.731+0000",
        "reportAlias": "trackingpixel",
        "email": "recipient1@fullbounce.invalid",
        "eventId": "56273dfbd4c6edc9107ec95c",
        "sendDate": "2015-10-21T07:26:09.147+0000",
        "sendingId": "56273e11d4c62cdd1be684f1",
        "customerId": "customer_xyz",
        "event": "5451f3b1e1c2485a5b71ca88",
        "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
  }
}
Response  200
HideShow

With anonymous tracking enabled reactions do not contain email, eventId, sendDate, sendingId and customerId.

Headers
Content-Type: application/json
Body
{
  "_embedded": {
    "reactions": [
      {
        "reactionType": "click",
        "reactionDate": "2015-10-21T07:26:10.731+0000",
        "reportAlias": "feature-link",
        "event": "5451f3b1e1c2485a5b71ca88",
        "trackingHash": "hU9kL-FT0kCLA960"
      },
      {
        "reactionType": "open",
        "reactionDate": "2015-10-21T07:26:10.731+0000",
        "reportAlias": "trackingpixel",
        "event": "5451f3b1e1c2485a5b71ca88",
        "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
  }
}
Response  400
HideShow

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/reactions?begin=2015-10-24T11:20:14.887%2B0000",
  "status": 400,
  "timestamp": "2015-10-23T11:22:01.827+0000"
}

Transaction Bounces

Transaction Bounces
GET/v1/bounces{?bounceType,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.000+0000' --data-urlencode 'end=2015-10-21T23:59:59.999+0000' '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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/bounces?bounceType=hardbounce&eventId=5534f2f3fcb24820d52f3413&sendingId=56273e12d4c62cdd1be68506&customerId=customer_xyz&email=recipient@fullbounce.invalid&begin=2015-10-21T11:00:33.000+0000&end=2015-10-21T11:00:33.000+0000&page=0&size=200
URI Parameters
HideShow
bounceType
enum (optional) Example: hardbounce

filters by the type of bounce as categorized by Inxmail Commerce

Choices: hardbounce softbounce

eventId
string (optional) Example: 5534f2f3fcb24820d52f3413

filters by the ID of a single transaction (as returned by /v1/event or /v1/eventsasmultipart)

sendingId
string (optional) Example: 56273e12d4c62cdd1be68506

filters by the ID of the sending of a mail (as included in an eventState entry in /v1/state/{id})

customerId
string (optional) Example: customer_xyz

filter by the customer ID that was specified in the event data

email
string (optional) Example: recipient@fullbounce.invalid

filter by the recipient email address (case insensitive, specify without personal part)

begin
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters bounces starting from this timestamp, in ISO-8601 format

end
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters bounces until this timestamp, in ISO-8601 format

size
number (optional) Default: 200 Example: 200

number of elements returned in a single response page (max. 500)

page
number (optional) Default: 0 Example: 0

result page number, if the request returns more results than the page size

Response  200
HideShow

bounceType is one of:

  • softbounce - Softbounce. For further information see Softbounce

  • hardbounce - Hardbounce. For further information see Hardbounce

Headers
Content-Type: application/json
Body
{
  "_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
  }
}
Response  400
HideShow

invalid 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": "/v1/bounces?begin=2015-10-24T11:20:14.887%2B0000",
  "status": 400,
  "timestamp": "2015-10-23T11:22:01.827+0000"
}

Transaction Complaints

Transaction Complaints
GET/v1/complaints{?complaintType,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.000+0000' --data-urlencode 'end=2015-10-21T23:59:59.999+0000' '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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/complaints?complaintType=feedbackloop&eventId=5534f2f3fcb24820d52f3413&sendingId=56273e12d4c62cdd1be68506&customerId=customer_xyz&email=recipient@fbl.invalid&begin=2015-10-21T11:00:33.000+0000&end=2015-10-21T11:00:33.000+0000&page=0&size=200
URI Parameters
HideShow
complaintType
enum (optional) Example: feedbackloop

filters by the type of complaint

Choices: feedbackloop

eventId
string (optional) Example: 5534f2f3fcb24820d52f3413

filters by the ID of a single transaction (as returned by /v1/event or /v1/eventsasmultipart)

sendingId
string (optional) Example: 56273e12d4c62cdd1be68506

filters by the ID of the sending of a mail (as included in an eventState entry in /v1/state/{id})

customerId
string (optional) Example: customer_xyz

filter by the customer ID that was specified in the event data

email
string (optional) Example: recipient@fbl.invalid

filter by the recipient email address (case insensitive, specify without personal part)

begin
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters complaints starting from this timestamp, in ISO-8601 format

end
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters complaints until this timestamp, in ISO-8601 format

size
number (optional) Default: 200 Example: 200

number of elements returned in a single response page (max. 500)

page
number (optional) Default: 0 Example: 0

result page number, if the request returns more results than the page size

Response  200
HideShow

complaintType is one of:

  • feedbackloop - FeedbackLoop. The recipient has marked the e-mail as spam.
Headers
Content-Type: application/json
Body
{
  "_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
  }
}
Response  400
HideShow

invalid 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/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

Blocklist
GET/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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/blocklist?begin=2015-10-21T11:00:33.000+0000&end=2015-10-21T11:00:33.000+0000&page=0&size=200
URI Parameters
HideShow
begin
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters blocked addresses starting from this timestamp, in ISO-8601 format

end
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters blocked addresses until this timestamp, in ISO-8601 format

size
number (optional) Default: 200 Example: 200

number of elements returned in a single response page (max. 500)

page
number (optional) Default: 0 Example: 0

result page number, if the request returns more results than the page size

Response  200
HideShow

Value of blockType is:

  • hardbounce - Recipient was blocked due to hardbounce threshold
Headers
Content-Type: application/json
Body
{
    "_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
    }
}
Response  400
HideShow

invalid 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/blocklist?begin=2015-10-24T11:20:14.887%2B0000",
  "status": 400,
  "timestamp": "2015-10-23T11:22:01.827+0000"
}

Single Blocked Email

Single Blocked Email
GET/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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/blocklist/blocked@domain.invalid
URI Parameters
HideShow
email
string (required) Example: blocked@domain.invalid

a single email address

Response  200
HideShow

Value of blockType is:

  • hardbounce - Recipient was blocked due to hardbounce threshold
Headers
Content-Type: application/json
Body
{
  "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"
    }
  }
}
Response  404
HideShow

A blocklist entry with this email does not exist

Body
{
  "exception": "com.inxmail.xcom.api.blocklist.EmailNotFound",
  "path": "/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 Email
DELETE/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

DELETE https://{spaceid}.api.inxmail-commerce.com/api-service/v1/blocklist/blocked@domain.invalid
URI Parameters
HideShow
email
string (required) Example: blocked@domain.invalid

a single email address

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "email": "blocked@domain.invalid",
    "blockType": "hardbounce",
    "blockDate": "2015-10-21T07:26:09.147+0000",
}
Response  404
HideShow

A blocklist entry with this email does not exist

Body
{
  "exception": "com.inxmail.xcom.api.blocklist.EmailNotFound",
  "path": "/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

Blacklist
GET/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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/blacklist?begin=2015-10-21T11:00:33.000+0000&end=2015-10-21T11:00:33.000+0000&page=0&size=200
URI Parameters
HideShow
begin
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters blocked addresses starting from this timestamp, in ISO-8601 format

end
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters blocked addresses until this timestamp, in ISO-8601 format

size
number (optional) Default: 200 Example: 200

number of elements returned in a single response page (max. 500)

page
number (optional) Default: 0 Example: 0

result page number, if the request returns more results than the page size

Response  200
HideShow

Value of blockType is:

  • explicit - Recipient was blocked due to manual blacklist entry
Headers
Content-Type: application/json
Body
{
    "_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
    }
}
Response  400
HideShow

invalid 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 Email
GET/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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/blacklist/blocked@domain.invalid
URI Parameters
HideShow
email
string (required) Example: blocked@domain.invalid

a single email address

Response  200
HideShow

Value of blockType is:

  • explicit - Recipient was blocked due to manual blacklist entry
Headers
Content-Type: application/json
Body
{
  "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"
    }
  }
}
Response  404
HideShow

A 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 Blacklist
DELETE/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

DELETE https://{spaceid}.api.inxmail-commerce.com/api-service/v1/blacklist/blocked@domain.invalid
URI Parameters
HideShow
email
string (required) Example: blocked@domain.invalid

a single email address

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "email": "blocked@domain.invalid",
    "blockType": "hardbounce",
    "blockDate": "2015-10-21T07:26:09.147+0000",
}
Response  404
HideShow

A 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
}

Add Email To Blacklist

Add Email To Blacklist
POST/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

POST https://{spaceid}.api.inxmail-commerce.com/api-service/v1/blacklist
Request
HideShow
Body
{
  "email": "toblock@domain.invalid"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "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"
    }
  }
}
Response  400
HideShow

Invalid or missing email address.

Headers
Content-Type: application/json
Body
{
  "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": "/v1/blacklist"
}

Send Raw Mail

Send a complete email message

Send a complete email message
POST/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

POST https://{spaceid}.api.inxmail-commerce.com/api-service/v1/sendrawmail
Request
HideShow
Body
{
  "message": "YXNkZnNhZGZhc2Rm..."
}
Response  200
HideShow

If 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"
}
Response  200
HideShow

If 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"
    }
  ]
}
Response  200
HideShow

If 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"
        }
    ]
}
Response  400
HideShow

Invalid or incomplete mime message, or invalid Base64 encoding

Headers
Content-Type: application/json
Body
{
  "exception": "org.springframework.mail.MailParseException",
  "path": "/v1/sendrawmail",
  "error": "Bad Request",
  "message": "Incomplete MimeMessage; nested exception is javax.mail.MessagingException: Incomplete MimeMessage",
  "timestamp": "2016-10-13T06:03:30.238+0000",
  "status": 400
}
Response  413
HideShow

Attachment(s) exceeds allowed size

Headers
Content-Type: application/json
Body
{
    "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 Sendings
GET/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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/relaysendings?email=recipient@somewhere.invalid&correlationId1=my-shop-identifier&correlationId2=my-campaign-identifier&correlationId3=my-mailing-identifier&begin=2015-10-21T11:00:33.000+0000&end=2015-10-21T11:00:33.000+0000&size=200&page=0
URI Parameters
HideShow
email
string (optional) Example: recipient@somewhere.invalid

filter by the recipient email address (case insensitive, specify without personal part)

correlationId1
string (optional) Example: my-shop-identifier

filters sendings with correlationId1 matching given search string

correlationId2
string (optional) Example: my-campaign-identifier

filters sendings with correlationId2 matching given search string

correlationId3
string (optional) Example: my-mailing-identifier

filters sendings with correlationId3 matching given search string

begin
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters sendings starting from this timestamp, in ISO-8601 format

end
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters sendings until this timestamp, in ISO-8601 format

size
number (optional) Default: 200 Example: 200

number of elements returned in a single response page (max. 500)

page
number (optional) Default: 0 Example: 0

result page number, if the request returns more results than the page size

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "_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
  }
}
Response  400
HideShow

invalid 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/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 Sending
GET/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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/relaysendings/56273e11d4c62cdd1be684f1
URI Parameters
HideShow
id
string (required) Example: 56273e11d4c62cdd1be684f1

a single relay sending ID

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "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"
    }
  }
}
Response  400
HideShow

ID 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/relaysendings/abc",
  "status": 400,
  "timestamp": "2015-12-08T11:08:19.203+0000"
}
Response  404
HideShow

A sending with this ID does not exist

Body
{
  "error": "Not Found",
  "exception": "com.inxmail.xcom.api.sendinginfo.SendingNotFound",
  "message": "Sending with id 5666b8bed4c6022b03786b72 not found",
  "path": "/v1/relaysendings/5666b8bed4c6022b03786b72",
  "status": 404,
  "timestamp": "2015-12-08T11:02:22.916+0000"
}

Mail Relay Reactions

Mail Relay Reactions
GET/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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/relayreactions?reactionType=click&email=recipient@somewhere.invalid&relaySendingId=56273e12d4c62cdd1be68506&correlationId1=my-shop-identifier&correlationId2=my-campaign-identifier&correlationId3=my-mailing-identifier&trackingHash=hU9kL-FT0kCLA960&begin=2015-10-21T11:00:33.000+0000&end=2015-10-21T11:00:33.000+0000&size=200&page=0
URI Parameters
HideShow
reactionType
enum (optional) Example: click

filters by the type of reaction

Choices: open click

email
string (optional) Example: recipient@somewhere.invalid

filter by the recipient email address (case insensitive, specify without personal part)

relaySendingId
string (optional) Example: 56273e12d4c62cdd1be68506

filters by the ID of the relay sending of a mail

correlationId1
string (optional) Example: my-shop-identifier

filters reactions with correlationId1 matching given search string

correlationId2
string (optional) Example: my-campaign-identifier

filters reactions with correlationId2 matching given search string

correlationId3
string (optional) Example: my-mailing-identifier

filters reactions with correlationId3 matching given search string

trackingHash
string (optional) Example: hU9kL-FT0kCLA960

filters by the tracking hash

begin
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters reactions starting from this timestamp, in ISO-8601 format

end
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters reactions until this timestamp, in ISO-8601 format

size
number (optional) Default: 200 Example: 200

number of elements returned in a single response page (max. 500)

page
number (optional) Default: 0 Example: 0

result page number, if the request returns more results than the page size

Response  200
HideShow

reactionType is one of:

  • open - Mailing was opened by the recipient

  • click - Link was clicked by the recipient

Headers
Content-Type: application/json
Body
{
  "_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
  }
}
Response  400
HideShow

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/relayreactions?begin=2015-10-24T11:20:14.887%2B0000",
  "status": 400,
  "timestamp": "2015-10-23T11:22:01.827+0000"
}

Mail Relay Bounces

Mail Relay Bounces
GET/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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/relaybounces?bounceType=hardbounce&correlationId1=my-shop-identifier&correlationId2=my-campaign-identifier&correlationId3=my-mailing-identifier&begin=2015-10-21T11:00:33.000+0000&end=2015-10-21T11:00:33.000+0000&page=0&size=200
URI Parameters
HideShow
bounceType
enum (optional) Example: hardbounce

filters by the type of bounce as categorized by Inxmail Commerce

Choices: hardbounce softbounce

correlationId1
string (optional) Example: my-shop-identifier

filters bounces with correlationId1 matching given search string

correlationId2
string (optional) Example: my-campaign-identifier

filters bounces with correlationId2 matching given search string

correlationId3
string (optional) Example: my-mailing-identifier

filters bounces with correlationId3 matching given search string

begin
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters bounces starting from this timestamp, in ISO-8601 format

end
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters bounces until this timestamp, in ISO-8601 format

email
string (optional) Example: recipient@somewhere.invalid

filter by the recipient email address (case insensitive, specify without personal part)

relaySendingId
string (optional) Example: 56273e12d4c62cdd1be68506

filters by the ID of the relay sending of a mail

size
number (optional) Default: 200 Example: 200

number of bounce elements returned in a single response page (max. 500)

page
number (optional) Default: 0 Example: 0

result page number, if the request returns more results than the page size

Response  200
HideShow

bounceType is one of:

  • softbounce - Softbounce. For further information see Softbounce

  • hardbounce - Hardbounce. For further information see Hardbounce

Headers
Content-Type: application/json
Body
{
  "_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
  }
}
Response  400
HideShow

invalid 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": "/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 Complaints
GET/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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/relaycomplaints?complaintType=feedbackloop&correlationId1=my-shop-identifier&correlationId2=my-campaign-identifier&correlationId3=my-mailing-identifier&begin=2015-10-21T11:00:33.000+0000&end=2015-10-21T11:00:33.000+0000&page=0&size=200
URI Parameters
HideShow
complaintType
enum (optional) Example: feedbackloop

filters by the type of complaint

Choices: feedbackloop

correlationId1
string (optional) Example: my-shop-identifier

filters complaints with correlationId1 matching given search string

correlationId2
string (optional) Example: my-campaign-identifier

filters complaints with correlationId2 matching given search string

correlationId3
string (optional) Example: my-mailing-identifier

filters complaints with correlationId3 matching given search string

begin
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters complaints starting from this timestamp, in ISO-8601 format

end
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters complaints until this timestamp, in ISO-8601 format

email
string (optional) Example: recipient@somewhere.invalid

filter by the recipient email address (case insensitive, specify without personal part)

relaySendingId
string (optional) Example: 56273e12d4c62cdd1be68506

filters by the ID of the relay sending of a mail

size
number (optional) Default: 200 Example: 200

number of complaint elements returned in a single response page (max. 500)

page
number (optional) Default: 0 Example: 0

result page number, if the request returns more results than the page size

Response  200
HideShow

complaintType is one of:

  • feedbackloop - Feedbackloop. The recipient has marked the e-mail as spam.
Headers
Content-Type: application/json
Body
{
  "_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
  }
}
Response  400
HideShow

invalid 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": "/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

Deliveries
GET/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

GET https://{spaceid}.api.inxmail-commerce.com/api-service/v1/deliveries?sendingId=5534f2f3fcb24820d52f3413&sendingType=`event`, `relay` or `test`,&email=recipient@company.invalid&status=sent&begin=2015-10-21T11:00:33.000+0000&end=2015-10-21T11:00:33.000+0000&page=0&size=200
URI Parameters
HideShow
sendingId
string (optional) Example: 5534f2f3fcb24820d52f3413

filters by the ID of a sending

sendingType
string (optional) Example: `event`, `relay` or `test`,

filter by the sending type (event for transaction sending, relay for mail relay sendings, test for test sendings)

email
string (optional) Example: recipient@company.invalid

filters by the recipient email address

status
string (optional) Example: sent

filters by the state

begin
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters deliveries starting from this timestamp, in ISO-8601 format

end
string (optional) Example: 2015-10-21T11:00:33.000+0000

filters deliveries until this timestamp, in ISO-8601 format

size
number (optional) Default: 200 Example: 200

number of elements returned in a single response page (max. 500)

page
number (optional) Default: 0 Example: 0

result page number, if the request returns more results than the page size

Response  200
HideShow

sendingType 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/json
Body
{
  "_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
  }
}
Response  400
HideShow

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/deliveries?begin=2015-10-24T11:20:14.887%2B0000",
  "status": 400,
  "timestamp": "2015-10-23T11:22:01.827+0000"
}

Generated by aglio on 01 Aug 2019