Skip to content

Using The Local API

Messages can be posted to ThinkAutomation via local HTTP GET or POST requests. Messages posted via the API will trigger an Automation to execute. Each of your configured Message Sources has a unique local API URL in the form:

https://localhost:9898/addmessage?taid={id}

or

http://localhost:9899/addmessage?taid={id}

You can add a Friendly Path to change the above URL to a unique path, eg:

https://localhost:9898/mycompany/customers/add

By default the ThinkAutomation Server accepts local API requests from local IP addresses only. You can add additional IP addresses to the Whitelist using the ThinkAutomation Server Settings.

You can change the port numbers for the HTTPS and HTTP interfaces using the ThinkAutomation Server Settings.

Any message posted to, or requested from, this URL will be passed to the ThinkAutomation server for immediate processing. Messages will be processed by the default Automation configured for the Message Source. There is no limit to the number of messages that can be posted to the local API. Messages can be sent to ThinkAutomation via the API regardless of the configured Message Source type.

The local API is designed to receive HTTP requests from your internal network only. It is not designed to be publicly accessible from the Internet. Whilst it is technically possible to expose the ThinkAutomation local API interface to the Internet, this is not recommended. To allow your ThinkAutomation Server to receive messages via public endpoints use the Web API instead. The Web API tunnel enables your ThinkAutomation Server to receive secure public HTTP requests whilst not being publicly accessibly itself.

The HTTPS interface for the local API uses a self-signed certificate by default. You can select a certificate in the Server Settings - Clients tab.

HTTP Get

The local API accepts HTTP GET requests. You can specify the message content as part of the URL. Whenever the URL is requested a new ThinkAutomation message will be created.

The body, subject, from & to addresses can be specified on the query string:

https://localhost:9898/addmessage?taid=5f7b421a6e1f408c38488397179
&from=alice%40test.com
&subject=unsubscribe
&body=testmessage

The body, subject, from and to query string parameters are optional.

Passing Field-Value Pairs

You can also pass specific field values using x-parametername=value. In this case the message passed to ThinkAutomation will be in Json format with each field value (excluding the 'x-').

For example:

https://localhost:9898/addmessage?taid=5f7b421a6e1f408c38488397179
&from=alice%40test.com
&subject=unsubscribe
&x-name=Alice+Bamber
&x-email=alice%40test.com

The message body which would be sent to ThinkAutomation as:

{
    "name": "Alice Bamber",
    "email": "alice@test.com"
}

If you do not want to use field=value pairs you can pass the raw body text using the &body= query string parameter. The ThinkAutomation message body will be set to the contents of the body parameter with no conversion.

HTTP Post

The local API accepts x-www-form-urlencoded, form-data, and raw post data formats.

Raw Data

For raw posts the post data can be set to the mime text of an email message. If mime text is not sent the ThinkAutomation Server will convert the message to mime text using the post data as the plain text message body.

Example:

Add Message local API URL:

https://localhost:9898/addmessage?taid=5f9ab14c6e1f405c7cbf955c

Post Data:

MIME-Version: 1.0
To: test@test.com
From: test@mycompany.com
Subject: Test Message

This is a test message

This would send a message to the Message Source with the above local URL. The Message would be processed by the default Automation configured for the Message Source.

x-www-form-urlencoded

This is the default for web form submissions. The Message Body passed to ThinkAutomation will be Json text with each field value. For example, suppose you post a web form with 2 fields Name=Test Name, Age=20, the message passed to ThinkAutomation will have the body:

{
    "Name": "Test",
    "Age": "20"
}

The from, to & subject can either be passed as post fields or as parameters on the URL query string.

Response

For each GET or POST the Local API will respond with a HTTP 202 Accepted status along with a Json response:

{
    "Success": true,
    "Cached": true,
    "ErrorMessage": "",
    "MessageResultDetail": null
}

Success will be true if the message was accepted, otherwise false and ErrorMessage will contain the reason.

Cached will always be true when using the local API.

If many messages are added in a short time period via the local API and the process queue becomes full a 503 status will be returned. You should check for a 503 status and retry.

Waiting For Automation Results

By default the local API POST and GET requests will respond with a 202 Accepted response as soon as the message has been queued (unless a &redirect parameter is specified). You can optionally wait for the Automation results by adding &wait=true to the URL. If the &wait=true parameter is used then the HTTP response will be sent back when the Automation has completed for the message (with a 200 OK response status). The response will include the Automation Return Value in the MessageResultDetail.

Example response if &wait=true parameter is used:

{
    "Success": true,
    "Cached": false,
    "ErrorMessage": "",
    "MessageResultDetail": {
        "MessageStoreId": "5f9befaf6e1f4065a89a5d9e",
        "MessageSourceId": "5f9ab14c6e1f405c7cbf955c",
        "IncomingUid": "dff8ad81-7ec2-4cc6-a288-975f7134ff85",
        "AutomationId": "5f86c3076e1f402260ea4bec",
        "AutomationSuccess": true,
        "AutomationError": "",
        "AutomationReturnValue": "Hello World",
        "AutomationLog": null,
        "ExecutionTime": 23
    }
}

Returning The Automation Return Value Only

You can choose to return the Automation Return value only by adding &results=true parameter to the URL instead of &wait=true. If the &results=true parameter is used then only the Automation Return Value content (or an error message) will be returned instead of the full Json response (shown above). Depending on the content of the Automation Return value text, the result will be served as plain text (text/plain), HTML (text/html) or Json (application/json). If the Return Value contains Markdown text it will be converted to HTML first. If the Return Value is already HTML it will be returned as HTML. If the Return Value is Json it will be returned as Json.

Returning Files

If the &results=true parameter is used and the Automation Return value is a single local file path (or a variable containing a file path) then the file content will be read and returned. You can return whole html pages, images, PDF files etc. The response Content-Type will be set according to the file extension.

Returning Files From The Embedded Files Store

If you are using the Embedded Files Store action to save files to the Embedded Files Store database, you can return file content directly from the Embedded File Store. Use the Embedded Files Store action with the Get Info operation. Assign the results of the Get Info operation to your Automation Return value. The ThinkAutomation Server will then read the file content directly from the database and return the content.

By default the ThinkAutomation Server only accepts HTTP requests from local IP addresses for the local API. You can add additional hosts to the Whitelist using the Server Settings.

Note: You should not make the local API public/internet facing. If you need to accept web forms, HTTP requests from the internet you should use the Web API or host your own ThinkAutomation Gateway Server. The Web API Gateway provides a secure proxy between public requests and your ThinkAutomation Server - preventing any malicious activity from affecting your ThinkAutomation server.

Sample API Calls C# & VB

The samples below show HTTP POST and GET against the local API. To use the public Web API replace the local URL (https://localhost:9898/addmessage?taid=xxx) with the public URL.

C# Post

public void SendMessage()
{
    using (HttpClient client = new HttpClient())
    {
        var values = new Dictionary<string, string>()
        {
            {"name","Alice Bamber"},
            {"email","alice@test.com"},
            {"subject","unsubscribe"},
            {"from","alice@test.com"}
        };
            var content = new FormUrlEncodedContent(values);
            var response = client.PostAsync("https://localhost:9898/addmessage?taid=5fcf74b96e1f4068c0f1b5c7", content).Result;
            Console.WriteLine(response.Content.ReadAsStringAsync.Result);
        }
}

C# Get

private void SendMessageUsingGet()
{
    using (HttpClient client = new HttpClient())
    {
        string URL = "https://localhost:9898/addmessage?taid=5fcf74b96e1f4068c0f1b5c7" + 
        "&from=" + HttpUtility.UrlEncode("alice@test.com") + 
        "&subject=" + HttpUtility.UrlEncode("unsucscribe") + 
        "&x-name=" + HttpUtility.UrlEncode("Alice Bamber") + 
        "&x-email=" + HttpUtility.UrlEncode("alice@test.com");
        var result = client.GetAsync(URL).Result;
        Console.WriteLine(result.StatusCode);
    }
}

Visual Basic .NET Post

Public Sub SendMessage()
    Using client As New HttpClient
        Dim values = New Dictionary(Of String, String) From {
            {"name", "Alice Bamber"}
            {"email", "alice@test.com"},
            {"subject", "unsubscribe"},
            {"from", "alice@test.com"}
        }
        Dim content = New FormUrlEncodedContent(values)
        Dim response = client.PostAsync("https://localhost:9898/addmessage?taid=5fcf74b96e1f4068c0f1b5c7", content).Result
        Console.WriteLine(response.Content.ReadAsStringAsync.Result)
    End Using
End Sub

Visual Basic .NET Get

Private Sub SendMessageUsingGet()
    Using client As New HttpClient
        Dim URL As String = "https://localhost:9898/addmessage?taid=5fcf74b96e1f4068c0f1b5c7" & _
        "&from=" & HttpUtility.UrlEncode("alice@test.com") & _
        "&subject=" & HttpUtility.UrlEncode("unsucscribe") & _
        "&x-name=" & HttpUtility.UrlEncode("Alice Bamber") & _
        "&x-email=" & HttpUtility.UrlEncode("alice@test.com")
        Dim result = client.GetAsync(URL).Result
        Console.WriteLine(result.StatusCode)
    End Using
End Sub

Specifying The Automation

By default the addmessage GET or POST will execute the default Automation assigned to the given Message Source. You can explicitly set the Automation to execute by adding &automationid={id} to the GET or POST query string. Automation Id's are shown on the Automation View Properties tab.

Local Web Forms

Any Web Form Message Sources can also be viewed and posted locally. The web form is served directly from the ThinkAutomation server - bypassing the Public API.

You can view the Local Form URL on the Message Source properties. The format of the URL is:

http://{serveraddress}:9899/form?taid={messagesourceid}

or

https://{serveraddress}:9898/form?taid={messagesourceid}

By default the ThinkAutomation Server accepts local API requests from local IP addresses only. You can add additional IP addresses to the Whitelist using the ThinkAutomation Server Settings.

You can change the port numbers for the HTTPS and HTTP interfaces using the ThinkAutomation Server Settings.

The secure URL (https) will display an certificate warning message in the web browser because the ThinkAutomation Server uses a self-signed certificate by default. You can add a trusted certificate using the ThinkAutomation Server Settings - Clients tab to avoid this warning.

Viewing Server Status

You can use the local http interface to view the ThinkAutomation Server status.

Use a web browser to view the address:

http://localhost:9899 or https://localhost:9898

This will display a web page showing server status, along with messages processed, queued and error counts for each Message Source and Automation.

You can request the status in Json format, by requesting the page:

http://localhost:9899/status.json or https://localhost:9898/status.json

The local API HTTPS interface uses a self-signed certificate by default. Most browsers will display a certificate warning. This can be ignored. The connection is still secure. You can add a trusted certificate using the Server Settings.

Message Store Local 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. The Message Store REST API can also be used to update and search the Embedded Knowledge Store.

See: ThinkAutomation Message Store REST API for details.