ThinkAutomation Logo

 

ThinkAutomation Message Store REST API

The ThinkAutomation Server provides a local HTTP REST API for accessing the Message Store. This can be used to integrate message store views with your own applications or to create custom front-ends to the ThinkAutomation message store using any development platform. This API will enable you to create a custom message store view with the same functionality as the Message Store view in the ThinkAutomation Studio.

You need ThinkAutomation version 5.0.871 or higher to use this API.

Endpoint

The ThinkAutomation Server listens on port 9898 for HTTPS requests and port 9899 for HTTP requests. The port numbers can be changed in your ThinkAutomation Server settings.

SecureNone Secure
https://localhost:9898/http://localhost:9899/

Replace 'localhost' with the IP/computer name of the ThinkAutomation Server when accessing remotely. You should always use the secure endpoint unless there is a specific reason not to.

Security

By default the ThinkAutomation Server uses a self-signed SSL certificate for HTTPS requests. This will cause warnings for direct requests from most browsers. You can assign a trusted certificate using the ThinkAutomation Server settings.

Whitelist

The ThinkAutomation server only accepts requests from IP addresses that have been included in the Whitelist. By default, localhost and 192.168.* are included. You can add additional IP ranges using the ThinkAutomation Server settings.

Responses

All successful responses are in JSON format. Successful responses will return a 200/202 HTTP response code. Unsuccessful responses will return a 400+ HTTP error status.

Authenticated users must have access to the SolutionID's used on requests. A 402 error will be returned if the user does not have access.

For any DELETE operations the authenticated user must have Can Delete Messages right enabled.


How To Use

The first step is to call authorize method with a valid username and password. The authorize method returns an authentication key.

Store the AuthKey property value from the authorize response. This must then be included on each subsequent method call (see below).

Store the MessageStoreFlags array from the authorize response if you want to provide a Flags filter on your message store view.

You should then call the solutions method to get a list of Solutions that the user has access to.

Store each Solution from the solutions response array. Each solution also includes an Automations array which contains details of each automation in the solution. Each automation includes MessagesTotal and MessagesToday properties allowing you to display message totals. Each automation includes a Folders array containing each sub-folder (or null if no sub-folders have been defined). The MessagesTotal property of each folder will contain the total number of messages in the folder.

You can now create a treeview style interface listing each solution, then each automation in the solution, followed by any sub-folders under each automation.

When a user selects an automation (and optionally a sub-folder) call the messagestorecount method to read a count of messages to setup paging. Then call the messagestorepage method to read each page of message summaries when pages are selected.

When a user selects a specific message call the messagestorebody method to get the detail and display.


Authentication

Before any calls can be made you must authenticate. A successful authorize response contains an AuthKey property value. This value must then be included with each subsequent request either as a authorization header or &authorization={authkey} query string parameter. The AuthKey will be valid for 7 days (or until your ThinkAutomation Server is restarted or the user password is changed).

GET: authorize

Authorize a user.

Example: http://localhost:9899/authorize?username={username}&password={password}

Returns

The MessageStoreFlags array contains a list of Message Store flags. Use this if you want to provide a Flags filter on your message store view.


Solutions

After authorizing you must call the solutions method to get a list of Solutions that the user has access to.

Get Solutions

GET: solutions

Get a list of Solutions that the authenticated user has access to.

Example: http://localhost:9899/solutions

Returns:

The array will contain a list of Solutions that the user has access to:

Each Solution object will contain arrays of MessageSources and Automations.

MessageSource Items :

The MessagesToday value contains the number of messages received by the message source for the current day.

Automation Items :

The MessagesToday value will contain the number of messages processed by the automation for the current day. The MessagesTotal value contains the total number of messages held in the message store for the Automation.

Each Automation will contain an array of Folders (or null if no sub-folders have been created).

Folder Items :

The MessagesTotal value contains the total number of messages held in the message store for the Automation/Folder.


Message Store View

Reading messages from the message store involves first requesting a count based on search criteria. The count will return the total number of messages for the given criteria. Message summaries are then requested by page. Each page will return a maximum of 1000 massages. So if the count returns 10,100 then this represents 11 pages number 1-11. The first 10 pages will return 1000 messages. The 11th page will return 100.

Get Message Store Count

GET: messagestorecount

Get a count of messages for the specified criteria.

Parameters:

Parameter NameValue
solutionidThe Solution ID.
automationidThe selected Automation ID.
folderidOptional. The selected Folder ID.
fromdateOptional. From message date (yyyy-mm-dd hh:mm:ss) UTC.
todateOptional. To message date (yyyy-mm-dd hh:mm:ss) UTC.
searchtextOptional. Search text. Only messages containing the search text in Subject, SentFrom, SentTo or AutomationReturnValue.
flagOptional (Integer). Include only messages with flag number.
returnonlyOptional (Integer). Include only messages 0=All, 1=Success only, 2=Failed only
sentitemsOptional (boolean). If true only return Sent Items.
outboxOptional (boolean). If true only return Outbox Items.

Example: http://localhost:9899/messagestorecount?solutionid=631602a0a703121a94f64ccc&automationid=631602efa703121a94f64cdc

Returns:

The IsCount value will be true. The Count value will contain the number of messages. Divide this by the RowsPerPage value to obtain the number of pages available.

Get Message Store Summaries Page

GET: messagestorepage

Get a page of message store message summaries.

Parameters:

Parameter NameValue
solutionidThe Solution ID.
automationidThe selected Automation ID.
pageThe page number.
folderidOptional. The selected Folder ID.
fromdateOptional. From message date (yyyy-mm-dd hh:mm:ss) UTC.
todateOptional. To message date (yyyy-mm-dd hh:mm:ss) UTC.
searchtextOptional. Search text. Only messages containing the search text in Subject, SentFrom, SentTo or AutomationReturnValue.
flagOptional (Integer). Include only messages with flag number.
returnonlyOptional (Integer). Include only messages 0=All, 1=Success only, 2=Failed only
sentitemsOptional (boolean). If true only return Sent Items.
outboxOptional (boolean). If true only return Outbox Items.

Example: http://localhost:9899/messagestorepage?solutionid=631602a0a703121a94f64ccc&automationid=631602efa703121a94f64cdc&page=1

Returns:

The Messages array will contain message summaries for each message in the requested page. If you requested Sent Items using the sentitems parameter then the SentItems array will be populated. If you requested Outbox Items using the outbox parameter then the Outbox array will be populated.

When reading message summaries the Mime, Body and AutomationLog properties will always be null. You can request the detail of an individual message using the messagestorebody or messagestoremessage methods.

Messages are returned in date order - newest first.

Message Detail

GET: messagestoremessage

Get the detail for a message including the full MIME text.

Parameters:

Parameter NameValue
solutionidThe Solution ID.
idThe Message ID.

Example: http://localhost:9899/messagestoremessage?solutionid=631602a0a703121a94f64ccc&id=631602faa703120d1c24a75d

The message id is obtained from the summary page : _id property of an individual message in the Messages array.

Returns:

The Mime value will contain the full email MIME text including attachments. The Body value will be blank.

The AutomationLog array will contain all Automation log lines for the processed message.

The AttachmentNames will contain a comma separated list of attachment file names (if any).

GET: messagestorebody

Get the detail for a message and the message body for previewing. This method differs from the messagestoremessage method in that the message body is returned ready for previewing. The messagestoremessage method returns the full MIME text of the message which you would need to decode to access the body.

Parameters:

Parameter NameValue
solutionidThe Solution ID.
idThe Message ID.

Example: http://localhost:9899/messagestorebody?solutionid=631602a0a703121a94f64ccc&id=631602faa703120d1c24a75d

The message id is obtained from the summary page : _id property of an individual message in the Messages array.

Returns:

The Body value will contain the message body in HTML format. You can then display this in a iframe tag to preview the message body. The Mime value will be blank.

The AutomationLog array will contain all Automation log lines for the processed message.

GET: messagestoreattachment

Get an attachment for a message.

Parameters:

Parameter NameValue
solutionidThe Solution ID.
idThe Message ID.
filenameThe Attachment filename.

Example: http://localhost:9899/messagestoreattachment?solutionid=631602a0a703121a94f64ccc&id=631602faa703120d1c24a75d&filename=test.txt

The message id is obtained from the summary page : _id property of an individual message in the Messages array. The filename is obtained from the AttachmentNames property.

Returns:

The Data value contains the base64 encoded binary data for the attachment.

DELETE: messagestoremessage

Deletes a message.

Parameters:

Parameter NameValue
solutionidThe Solution ID.
idThe Message ID.

GET: messagestoresentitem

Gets the detail for any Sent Item message.

Parameters:

Parameter NameValue
solutionidThe Solution ID.
idThe Sent Item Message ID.

Example: http://localhost:9899/messagestoresentitem?solutionid=631602a0a703121a94f64ccc&id=631602faa703120d1c24b324

The message id is obtained from the summary page : _id property of an individual message in the SentItems array.

DELETE: messagestoresentitem

Deletes a message store Sent Item message.

Parameters:

Parameter NameValue
solutionidThe Solution ID.
idThe Sent Item Message ID.

GET: messagestoreoutboxitem

Gets the detail for any Outbox message.

Parameters:

Parameter NameValue
solutionidThe Solution ID.
idThe Outbox Item Message ID.

Example: http://localhost:9899/messagestoreoutboxitem?solutionid=631602a0a703121a94f64ccc&id=631602faa703120d1c24c253

The message id is obtained from the summary page : _id property of an individual message in the Outbox array.

DELETE: messagestoreoutboxitem

Deletes an Outbox item.

Parameter NameValue
solutionidThe Solution ID.
idThe Outbox Item Message ID.

Reprocessing Messages

Individual message store messages can be reprocessed by ThinkAutomation. The selected message will be added back to the process queue and processed again by the Automation.

GET: messagestorereprocessmessage

Parameter NameValue
solutionidThe Solution ID.
idThe Message ID.

Folders

Messages in the Message Store are assigned an AutomationId. This is the Automation that processed the message. Messages can also be assigned a FolderId - which is the optional subfolder id. Users can create sub-folders using the ThinkAutomation Studio and messages can be assigned a folder during Automation processing.

Update Folder

POST: messagestorefolder

Adds or updates a message store folder.

Parameters:

Parameter NameValue
solutionidThe Solution ID.
automationidThe Automation ID.

Post Body:

If the FolderId value is blank then a new folder is created otherwise the existing folder is updated. If a ParentId is specified then parent folder must exist (within the same Automation). The folder will be added as a child of the parent. The SolutionId and AutomationId parameters must be specified, and the automation specified must belong to the solution specified.

Returns:

 

Delete Folder

DELETE: messagestorefolder

Delete a message store folder.

Important: All messages in the folder and any sub-folders will also be deleted.

Parameters:

Parameter NameValue
solutionidThe Solution ID.
folderidThe Folder ID.

Processed Messages Summary

You can request counts of processed and failed messages for a Solution and search criteria. You can use this data to provide a dashboard style view of your ThinkAutomation server processing load.

GET: messagestoresummary

Get daily counts of processed messages for the specified criteria.

Parameters:

Parameter NameValue
solutionidThe Solution ID.
automationidOptional. The selected Automation ID.
fromdateOptional. From execution date (yyyy-mm-dd).
todateOptional. To execution date (yyyy-mm-dd).
searchtextOptional. Search text. Only messages containing the search text in Subject, SentFrom, SentTo or AutomationReturnValue.
flagOptional (Integer). Include only messages with flag number.

Example: http://localhost:9899/messagestoresummary? solutionid=631602a0a703121a94f64ccc&fromate=2022-09-07&todate=2022-09-08

Returns:

The top level Success, Failed, Bytes and ExecuteMS (execution time in milliseconds) values contain the totals of messages processed for all Automations in the Solution (unless you have requested a single Automation with the &automationid parameter).

The Automations array contains each Automation.

Each Automation has a Days array containing the totals for each day within the requested fromdate and todate.

The from and to dates related to the Automation Execution Date - not the date of the message (which could be different based on the Message Source).


ThinkAutomation Business Process Automation Software. Copyright (c) 2022 Parker Software Limited.