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.
| Secure | None 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
{ "UserName": "Admin", "Name": "System Administrator", "Email": "test@mycompany.com", "AuthKey": "84C528A85976822B9B4253B311E4DC877A3544A3C0170251", "Rights": { "Administrator": false, "SystemAdministrator": true, "CanViewMessageSources": true, "CanReprocess": true, "CanViewLogs": true, "CanViewMessageStore": true, "CanDeleteMessages": true, "CanEditProperties": true, "CanEditCustomActions": true }, "RegisteredUser": "My Company", "MessageStoreFlags": [ { "Number": 1, "Description": "Blue Flag", "ColorHex": "#FF6A94C8" }, { "Number": 2, "Description": "Green Flag", "ColorHex": "#FF92B250" }, { "Number": 3, "Description": "Yellow Flag", "ColorHex": "#FFFFFF00" } ]}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:
xxxxxxxxxx[ { "Id": "631602a0a703121a94f64ccc", "Name": "Sales Processing", "Enabled": true, "MessageSources": [ { "Id": "631602b1a703121a94f64cda", "Name": "Office 365 Sales", "SourceDescription": "Sales Team (Inbox)", "Enabled": true, "MessagesToday": 18, "BytesReceived": 139466, "LastError": "" } ], "Automations": [ { "Id": "631602efa703121a94f64cdc", "Name": "Office 365 Sales Automation", "Enabled": true, "MessagesTotal": 0, "MessagesToday": 18, "MessagesOut": 0, "MessagesFailed": 0, "LastError": "", "Folders": [ { "Id": "63160308a703121a94f64ce9", "ParentId": "", "Name": "New", "MessagesTotal": 6 }, { "Id": "63160310a703121a94f64ceb", "ParentId": "", "Name": "Quoted", "MessagesTotal": 3 } ] } ] }]The array will contain a list of Solutions that the user has access to:
xxxxxxxxxx{ "Id": "631602a0a703121a94f64ccc", "Name": "Solution Name", "Enabled": true, "MessageSources": [], "Automations": []} Each Solution object will contain arrays of MessageSources and Automations.
MessageSource Items :
xxxxxxxxxx{ "Id": "631602b1a703121a94f64cda", "Name": "Message Source Name", "SourceDescription": "", "Enabled": true, "MessagesToday": 0, "BytesReceived": 0, "LastError": ""}The MessagesToday value contains the number of messages received by the message source for the current day.
Automation Items :
xxxxxxxxxx{ "Id": "631602efa703121a94f64cdc", "Name": "Automation Name", "Enabled": true, "MessagesTotal": 0, "MessagesToday": 0, "MessagesOut": 0, "MessagesFailed": 0, "LastError": "", "Folders": []}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 :
xxxxxxxxxx{ "Id": "63160308a703121a94f64ce9", "ParentId": "", "Name": "Folder Name", "MessagesTotal": 0}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 Name | Value |
|---|---|
| solutionid | The Solution ID. |
| automationid | The selected Automation ID. |
| folderid | Optional. The selected Folder ID. |
| fromdate | Optional. From message date (yyyy-mm-dd hh:mm:ss) UTC. |
| todate | Optional. To message date (yyyy-mm-dd hh:mm:ss) UTC. |
| searchtext | Optional. Search text. Only messages containing the search text in Subject, SentFrom, SentTo or AutomationReturnValue. |
| flag | Optional (Integer). Include only messages with flag number. |
| returnonly | Optional (Integer). Include only messages 0=All, 1=Success only, 2=Failed only |
| sentitems | Optional (boolean). If true only return Sent Items. |
| outbox | Optional (boolean). If true only return Outbox Items. |
Example:
http://localhost:9899/messagestorecount?solutionid=631602a0a703121a94f64ccc&automationid=631602efa703121a94f64cdc
Returns:
xxxxxxxxxx{ "Messages": null, "SentItems": null, "Outbox": null, "_id": "63160666a7031217d496c3ac", "SolutionId": "631602a0a703121a94f64ccc", "MessageSourceId": "", "AutomationId": "631602efa703121a94f64cdc", "FolderId": "", "FromDate": "0001-01-01T00:00:00", "ToDate": "0001-01-01T00:00:00", "SearchText": "", "Flag": 0, "ReturnOnly": 0, "PageNumber": 0, "RowsPerPage": 1000, "IsCount": true, "IsDelete": false, "IsSentItems": false, "IsOutbox": false, "Count": 9}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 Name | Value |
|---|---|
| solutionid | The Solution ID. |
| automationid | The selected Automation ID. |
| page | The page number. |
| folderid | Optional. The selected Folder ID. |
| fromdate | Optional. From message date (yyyy-mm-dd hh:mm:ss) UTC. |
| todate | Optional. To message date (yyyy-mm-dd hh:mm:ss) UTC. |
| searchtext | Optional. Search text. Only messages containing the search text in Subject, SentFrom, SentTo or AutomationReturnValue. |
| flag | Optional (Integer). Include only messages with flag number. |
| returnonly | Optional (Integer). Include only messages 0=All, 1=Success only, 2=Failed only |
| sentitems | Optional (boolean). If true only return Sent Items. |
| outbox | Optional (boolean). If true only return Outbox Items. |
Example:
http://localhost:9899/messagestorepage?solutionid=631602a0a703121a94f64ccc&automationid=631602efa703121a94f64cdc&page=1
Returns:
xxxxxxxxxx{ "Messages": [ { "_id": "631602faa703120d1c24a75d", "SolutionId": "631602a0a703121a94f64ccc", "MessageSourceId": "631602b1a703121a94f64cda", "IncomingUid": "AAMkADdmM2MzZDNiLTNmNTctNGE4gBGAAAAAADGimcp7ED3Sacl9O", "Subject": "ThinkAutomation Evaluation Registration", "SentFrom": "no-reply@parkersoftware.com", "SentTo": "\"Sales\" <sales@parkersoftware.com>", "Importance": "N", "MessageDate": "2022-07-05T11:33:49", "MessageFlags": 0, "MessageSize": 7842, "AutomationId": "631602efa703121a94f64cdc", "AutomationPending": false, "AutomationSuccess": true, "AutomationError": false, "AutomationErrorValue": "", "AutomationReturnValue": "", "AutomationDate": "2022-09-05T14:08:58.273286", "AutomationLog": null, "Attachments": false, "AttachmentNames": "", "Mime": null, "Body": null }, { . } ], "SentItems": null, "Outbox": null, "_id": "63160682a7031217d496c3ad", "SolutionId": "631602a0a703121a94f64ccc", "MessageSourceId": "", "AutomationId": "631602efa703121a94f64cdc", "FolderId": "", "FromDate": "0001-01-01T00:00:00", "ToDate": "0001-01-01T00:00:00", "SearchText": "", "Flag": 0, "ReturnOnly": 0, "PageNumber": 1, "RowsPerPage": 1000, "IsCount": false, "IsDelete": false, "IsSentItems": false, "IsOutbox": false, "Count": 0}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 Name | Value |
|---|---|
| solutionid | The Solution ID. |
| id | The 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:
xxxxxxxxxx{ "_id": "631602faa703120d1c24a75d", "SolutionId": "631602a0a703121a94f64ccc", "MessageSourceId": "631602b1a703121a94f64cda", "IncomingUid": "AAMkADdmM2MzZDNiLTNmNTctNGE4gBGAAAAAADGimcp7ED3Sacl9O", "Subject": "ThinkAutomation Evaluation Registration", "SentFrom": "no-reply@parkersoftware.com", "SentTo": "\"Sales\" <sales@parkersoftware.com>", "Importance": "N", "MessageDate": "2022-07-05T11:33:49", "MessageFlags": 0, "MessageSize": 7842, "AutomationId": "631602efa703121a94f64cdc", "AutomationPending": false, "AutomationSuccess": true, "AutomationError": false, "AutomationErrorValue": "", "AutomationReturnValue": "", "AutomationDate": "2022-09-05T14:08:58.273286", "AutomationLog": [ { "MessageStoreId": "631602faa703120d1c24a75d", "AutomationId": "631602efa703121a94f64cdc", "LineNumber": 0, "Dated": "2022-09-05T14:08:58.25765", "IsError": false, "LineText": "Process Message, Dated 7/5/2022 12:33:49 PM, From no-reply@parkersoftware.com, (7.7KB), Subject: ThinkAutomation Evaluation Registration", "NodeName": "SPVMWINDOWS2019" } ], "Attachments": false, "AttachmentNames": "", "Mime": "//full mime text//", "Body": null,}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 Name | Value |
|---|---|
| solutionid | The Solution ID. |
| id | The 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:
xxxxxxxxxx{ "_id": "631602faa703120d1c24a75d", "SolutionId": "631602a0a703121a94f64ccc", "MessageSourceId": "631602b1a703121a94f64cda", "IncomingUid": "AAMkADdmM2MzZDNiLTNmNTctNGE4gBGAAAAAADGimcp7ED3Sacl9O", "Subject": "ThinkAutomation Evaluation Registration", "SentFrom": "no-reply@parkersoftware.com", "SentTo": "\"Sales\" <sales@parkersoftware.com>", "Importance": "N", "MessageDate": "2022-07-05T11:33:49", "MessageFlags": 0, "MessageSize": 7842, "AutomationId": "631602efa703121a94f64cdc", "AutomationPending": false, "AutomationSuccess": true, "AutomationError": false, "AutomationErrorValue": "", "AutomationReturnValue": "", "AutomationDate": "2022-09-05T14:08:58.273286", "AutomationLog": [ { "MessageStoreId": "631602faa703120d1c24a75d", "AutomationId": "631602efa703121a94f64cdc", "LineNumber": 0, "Dated": "2022-09-05T14:08:58.25765", "IsError": false, "LineText": "Process Message, Dated 7/5/2022 12:33:49 PM, From no-reply@parkersoftware.com, (7.7KB), Subject: ThinkAutomation Evaluation Registration", "NodeName": "SPVMWINDOWS2019" } ], "Attachments": true, "AttachmentNames": "text.txt", "Mime": "", "Body": "<html><body><p>This is the message body</p></body></html>"}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 Name | Value |
|---|---|
| solutionid | The Solution ID. |
| id | The Message ID. |
| filename | The 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:
xxxxxxxxxx{ "MessageId": "63ca723a90ca1b0c10d051ef", "FileName": "test.txt", "ContentType": "application/octet-stream", "ContentId": "", "Size": 2431, "Data": "RDpcQ29kZVNpZ25cc2lnbnRvb2wuZXhlIHNpZ24gL3QgImh0dHA6Ly90aW1lc3RhbXAuZGlnaWNlcnQuY29tIiAvZiAiRDpcQ29kZVNpZ25cUEFSS0VSIFNPRlRXQVJFIExJTUlURUQgLSBDb2Rlc2lnbiAyMDIyLTIzLnBmeCIgL3AgIiZKcDN7Ml84XSFEZjcuOTw1Pi........"}The Data value contains the base64 encoded binary data for the attachment.
DELETE: messagestoremessage
Deletes a message.
Parameters:
| Parameter Name | Value |
|---|---|
| solutionid | The Solution ID. |
| id | The Message ID. |
GET: messagestoresentitem
Gets the detail for any Sent Item message.
Parameters:
| Parameter Name | Value |
|---|---|
| solutionid | The Solution ID. |
| id | The 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 Name | Value |
|---|---|
| solutionid | The Solution ID. |
| id | The Sent Item Message ID. |
GET: messagestoreoutboxitem
Gets the detail for any Outbox message.
Parameters:
| Parameter Name | Value |
|---|---|
| solutionid | The Solution ID. |
| id | The 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 Name | Value |
|---|---|
| solutionid | The Solution ID. |
| id | The 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 Name | Value |
|---|---|
| solutionid | The Solution ID. |
| id | The 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 Name | Value |
|---|---|
| solutionid | The Solution ID. |
| automationid | The Automation ID. |
Post Body:
xxxxxxxxxx{ "FolderId": "", "ParentId": "", "Name": "New Folder"}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:
xxxxxxxxxx{ "FolderId": "6319af04a7031218d857f7c7", "ParentId": "", "Name": "New Folder", "MessagesTotal": 0}
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 Name | Value |
|---|---|
| solutionid | The Solution ID. |
| folderid | The 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 Name | Value |
|---|---|
| solutionid | The Solution ID. |
| automationid | Optional. The selected Automation ID. |
| fromdate | Optional. From execution date (yyyy-mm-dd). |
| todate | Optional. To execution date (yyyy-mm-dd). |
| searchtext | Optional. Search text. Only messages containing the search text in Subject, SentFrom, SentTo or AutomationReturnValue. |
| flag | Optional (Integer). Include only messages with flag number. |
Example:
http://localhost:9899/messagestoresummary?
solutionid=631602a0a703121a94f64ccc&fromate=2022-09-07&todate=2022-09-08
Returns:
xxxxxxxxxx{ "SolutionId": "631602a0a703121a94f64ccc", "AutomationId": "", "FromExecutionDate": "2022-09-01T00:00:00", "ToExecutionDate": "2022-09-14T00:00:00", "SearchText": "", "Flag": 0, "Success": 2, "Failed": 0, "Bytes": 1452, "ExecuteMS": 4713, "Automations": [ { "AutomationId": "631602efa703121a94f64cdc", "Success": 2, "Failed": 0, "Bytes": 1452, "ExecuteMS": 4713, "Days": [ { "Dated": "2022-09-07T00:00:00", "Success": 1, "Failed": 0, "Bytes": 726, "ExecuteMS": 4661 }, { "Dated": "2022-09-08T00:00:00", "Success": 1, "Failed": 0, "Bytes": 726, "ExecuteMS": 52 } ] } ]}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.