Introducing IntriMail - API -
Welcome to IntriMail API documentation. You can use our API to submit jobs, and update or query pack statuses. Version 1 of the API was open to selected partners, the first fully public API is version 2 and is available on 2.5 (Broadway) systems and later. If your system is configured with a custom domain name (outside *intrimail.dms.co.uk) then you can also use your custom domain name when accessing the API.
Authentication
Acquire a Token
​
The authentication call will return you a token for use in the Authorization header for all API calls. This ticket is valid for 1 hour, after which time you must acquire a new one.
​
HTTP Request
​
POST /api/v2/authenticate
​
IntriMail expects for the authentication token to be included in all other API requests in a header that looks like the following:
​
Authorization: Bearer [token]
(i) You must replace [token] with your authentication token.
To acquire an authentication token:
​
POST /api/v2/authenticate
​
​
{
"email": "test@test.com",
"password": "MySecurePassword",
"accountLogin": "MyAccountLogin"
}
​
​
If successful, the POST will return you an authentication token in the form of JWT.
​
{
"result": {
"code": 200,
"description": "Success"
},
"token": "[token]"
}
​
Submission
A typical submission will consist of the following steps:
-
Acquire an authentication token, if you don't already have a valid one.
-
Optionally, acquire the account configuration to use when generating the print options for your document, or to validate that the print options you intend on using are still valid
-
Initialse the print submission using /api/v2/print/init
-
One or more calls to /api/v2/print/docpart to provide the document data
-
Zero or more calls to /api/v2/print/attpart to provide any attachment data
-
A final call to /api/v2/print/commit to commit the document for processing
​
Get Account Configuration
​
This endpoint gets all print options available to the authenticated user and can be used to construct the JSON describing the print options requested for a submission.
HTTP Request
GET /api/v2/print/configuration
​
Headers
​
Parameter - Description
Authorization Your authentication token preceded by "Bearer"
​
*Remember to pass your authentication token in the Authorization header
An authenticated call to this endpoint returns JSON structured as follows:
​
[
"result": {
"code": 200,
"description": "Success"
},
"config": {
"content":"Example print config json"
}
]
Initialise a Submission
This endpoint initialises a print job submission, allows you to specify the print options you want to use for the submission, and returns you a job GUID which you will use with your subsequent calls to provide the document data and signal that the job is ready for processing.
​
For each of the six mandatory print options (paper, envelope, deliveryMethod, colourMode and packMode) either GUID or name can be used. If both are provided, GUID is used. A print option's GUID will change if the option is deleted then re-created via self-service.
Please note:
-
clientId can be any string value up to a limit of 255 chars. This is for your reference only, for fault-finding and to support future reporting.
-
name is the name of the document you're submitting, this is how the document will be displayed in the console
-
languageCode is reserved for future enhancements and currently should always be set to en
-
specialHandling is a free-text value which should be set in agreement with the print provider. If you are unusure, leave this blank or omit the value.
HTTP Request
POST /api/v2/print/init
​
Headers
​
Header Name - Description
Authorization Your authentication token preceded by "Bearer"
POST /api/v2/print/init
Authorization: Bearer [token]
​
The POST body will be JSON text indicating the print options to be used with this submission. The values here are for example purposes only and the actual values used should be taken from the configuration of your account.
​
{
"clientId": "your-client-software-name-and-version-here",
"name": "letter-for-submission.pdf",
"delayUntil": "2018-12-24",
"languageCode": "en",
"paper": {
"guid": "...",
"name": "A4"
},
"envelope": {
"guid": "...",
"name": "C4"
},
"stationery": {
"guid": "...",
"name": "IntriMail Headed"
},
"ink": {
"guid": "...",
"name": "Full Colour"
},
"delivery": {
"guid": "...",
"name": "First Class"
},
"packMode": {
"guid": "...",
"name": "Single packs"
},
"duplex": {
"guid": "...",
"name": "Yes"
},
"specialHandling": "",
"copyTo": [
{
"address": "16 Northumberland Road\nOxford\nOX4 3EE",
"delayUntil": "2018-12-25",
"coveringMesage": "Put this on the covering sheet",
"includeAttachments": true
},
{
"address": "8 Oystermouth Road\nSwansea\nSA1 1AA",
"includeAttachments": false,
"deliveryOverride": {
"name": "2nd Class"
}
}
],
"inserts": [
{ "guid": "..." },
{ "guid": "..."}
],
"signature": {
"guid": "...",
"name": "account-level signature"
}
}
​
The above call returns JSON containing the result code along with a "job GUID" and details of the public key you should use to encrypt your document data (if you set generateKey to true in your print options).
​
{
"jobGUID": "12345678-1234-1234-1234-123456789012",
"result": {
"code": 200,
"description": "Success"
}
}
Send Document Data
​
This endpoint allows you to submit your document data. If the document is larger than 200KB it must be split into parts not exceeding 200KB, and the parts must be submitted consecutively and in the correct order.
HTTP Request
POST /api/v2/print/docpart
​
Headers
​
Header Name - Description
Authorization Your authentication token preceded by "Bearer"
​
hpod-jobguid The GUID of the job you're submitting document data for
​
hpod-totalsize The total size of the document being submitted (a sum of all the parts)
​
hpod-part A zero-based index indicating the position of this part within the attachment file
​
hpod-filetype A 3-letter file type extension indicting the file type
POST /api/v2/print/docpart
Authorization: Bearer [token]
hpod-jobguid: 12345678-1234-1234-1234-123456789012
hpod-totalsize: 12345678
hpod-part: 0
[Raw file data is provided in the body]
The above command returns JSON structured like this:
​
{
"totalReceived": 95830,
"result": {
"code": 200,
"description":"Success"
}
}
totalReceived indicates the volume of data, in bytes, received for the document so far
Send Attachment Data
​
This endpoint allows you to submit your attachment file data. If the document is larger than 200KB it must be split into parts not exceeding 200KB, and the parts must be submitted consecutively and in the correct order.
HTTP Request
POST /api/v2/print/attpart
​
Headers
​
Header Name - Description
Authorization Your authentication token preceded by "Bearer"
​
hpod-jobguid The GUID of the job you're submitting document data for
​
hpod-fileindex A zero-based index indicating the position of this attachment within the submission
​
hpod-filename The name of the file, used for display purposes only
​
hpod-totalsize The total size of the attachment
(a sum of all the parts)
​
hpod-part A zero-based index indicating the position of this part within the attachment file
POST /api/v2/print/attpart
Authorization: Bearer [token]
hpod-jobguid: 12345678-1234-1234-1234-123456789012
hpod-attindex: 0
hpod-totalsize: 1048576
hpod-filename: attachment_1.pdf
hpod-part: 0
[Raw file data is provided in the body]
The above command returns JSON structured like this:
​
{
"totalReceived": 1395304,
"result": {
"code": 200,
"description":"Success"
}
}
totalReceived indicates the volume of data, in bytes, received for the document so far
Commit Submission for Processing
​
This endpoint allows you to indicate to IntriMail that all document and attachment parts have been submitted and the document is ready to be committed to the system for processing.
HTTP Request
GET /api/v2/print/commit
​
Headers
​
Header Name - Description
Authorization Your authentication token preceded by "Bearer"
​
hpod-jobguid The GUID of the job you're submitting document data for
​
​
Example submission​
​
Suppose you have an account configured with Myco Stationery, a Full Colour ink setting, A4 paper, a C5 envelope, and a 1st Class delivery method, you want to submit a duplex job and you'll be submitting a mail merge (i.e. multiple packs in a single job). You don't want to delay your submission, you want it processed and sent out as soon as possible. Based on the results you'd receive from the /api/v2/print/configuration endpoint you could construct a submission as displayed to the right.
​
GET /api/v2/print/commit
Authorization: Bearer [token]
hpod-jobguid: 12345678-1234-1234-1234-123456789012
The above command returns JSON structured like this:
​
{
"result": {
"code": 200,
"description":"Success"
}
}
​
​
​
​
​
​
​
POST / api/v2/print/init
Authorization: Bearer [token]
​
{
"clientId": "my-client",
"name": "mailmerge.pdf",
"languageCode": "en",
"paper": {
"name": "A4"
},
"envelope": {
"name": "C5"
},
"stationery": {
"name": "Myco Stationery"
},
"ink": {
"name": "Full Colour"
},
"delivery": {
"name": "1st Class"
},
"packMode": {
"name: "Multi packs"
},
"duplex": {
"name": "Yes"
},
"electronicDelivery": {
"enabled": true
}
}
​
​
This would return you the submission's GUID, referred to as [JobGUID] below. The PDF file you're submitting is 650,000 bytes.
​
​
POST /apit/v2/print/docpart
Authorization: Bearer [token]
hpod-jobguid: [JobGUID]
hpod-totalsize: 650000
hpod-part: 0
hpod-filetype: pdf
​
[The first 500,000 bytes of the raw file data is provided in the body]
​
​
POST /apit/v2/print/docpart
Authorization: Beaer [token]
hpod-jobguid: [JobGUID]
hpod-totalsize: 650000
hpod-part: 1
hpod-filetype: pdf
​
[The remaining 150,000 bytes of the raw file data is provided in the body]
​
​
GET /apit/v2/print/commit
Authorization: Beaer [token]
hpod-jobguid: [JobGUID]
​
​
After this call your submission will be committed for processing. You can then use the console to review and manage your submissions.
PP
​
Pack Status
Use this endpoint for updating a pack to a new status.
​
​
Update Pack Status
​
The POST body will be some JSON text describing the packs you want to update, and the status you want to update them to. The authenticated user should be in an account at the same level or higher in the account hierarchy than the account that owns the pack. At most, 100 packs can be updated in a single call.
HTTP Request
POST /api/v2/pack/status
​
Headers
​
Header Name - Description
Authorization Your authentication token preceded by "Bearer"
​
​
POST /api/v2/pack/status
Authorization: Bearer [token]
​
[
{
"GUID": "12345678-1234-2345-3456-123456789012",
"status": "Returned",
"notificationDateUTC": "1 Jan 2019 12:00",
"context": "Not at this Address"
}
]
​
​
notificationDate is optional. If omitted, the current date/time is used for the status transition timestamp.
​
context is optional, if provided the text is stored against the status transition, for potential reporting or console display as appropriate.
The above command returns JSON text to indicate whether the operation for each pack was successful, eg:
​
[
{
"GUID": "12345678-1234-2345-3456-123456789012",
"result": {
"code": 200,
"description":"Success"
}
}
]
Result Objects and Status Codes
The IntriMail API uses the following status codes in the return values. If further context is indicated, it will be provided as plain text in the "content" member of the status object.
​
​
Error Code - Meaning
200 Success -- The request was successfully processed.
​
400 Failed -- The request failed, further information may be in the context member.
​
401 Unauthorized -- Your credentials are wrong or the token is invalid or has expired.
​
403 Forbidden -- Your authentication token is not permitted to access this resource..
​
404 Not Found -- The resource you requested does not exist.
​
406 Not Acceptable -- You requested a format that isn't JSON.
​
429 Too Many Requests -- You have exceeded the configured API call rate for your account.
​
500 Internal Server Error -- We had a problem with our server. Try again later.
​
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
An example result object for a call to submit a document for printing on A4 when the account has no A4 paper configured.
​
{
"code": 400,
"description": "Failed",
"context": "Requested print option does not exist: Paper / A4"
}
Terminology
-
Submission / Job - the document you submit to IntriMail for processing
-
Pack - the individual letters produced from your submission
The key benefits of IntriMail
Flexible Working
Create and send documents straight from your desktop, laptop, server or mobile device
Cost Effective
Reduce print, fulfilment and postage costs by as much as 60%
Traceable
Track your documents throughout the entire process from creation through to delivery
Secure
Encryption and secure data processing of each page of every document from receipt to dispatch
Quality
High quality print and finishing with detailed reporting and accredited integrity at every step of the process