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:

  1. Acquire an authentication token, if you don't already have a valid one.

  2. 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

  3. Initialse the print submission using /api/v2/print/init

  4. One or more calls to /api/v2/print/docpart to provide the document data

  5. Zero or more calls to /api/v2/print/attpart to provide any attachment data

  6. 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.

 

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                                      withint he submission

hpod-filename       The name of the file, used for                                       display purposes only

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

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 recieve from the /api/v2/print/configuration endpoint you could constrcut 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"

    },

}

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: Beaer [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 these endpoints for querying the status of a pack or 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"

}

 

The key benefits of IntriMail

Terminology

 - Submission / Job - the document you submit to IntriMail for processing

- Pack - the individual letters produced from your submission

 

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

Contact us

Call.png

Call us on

020 3915 3913 

Email.png
Chat2.png

Click to

Live Chat

 

Fluxs House, Fluxs Lane, Epping, Essex, CM16 7PE

Follow:

  • LinkedIn Social Icon
  • Facebook Social Icon
  • Twitter Social Icon
  • Google+ Social Icon

©2020 by Digital Mailing Solutions Ltd

Authorised and Regulated by the FCA