Email Classification

The purpose of this flow is to provide a step-by-step guide to integrating the Blockbrain API for automated email classification.

1. Introduction

The intended use case is to classify incoming emails according to a predefined rule set. The classification logic is configured in the Blockbrain UI and can be accessed via the API for automation purposes.

All functionality available in the UI is also exposed through the API. The UI should be used to set up the classification bot and its prompt, while the API should be used to implement automated or large-scale workflows. The complete Blockbrain API documentation is provided here: https://blocky.theblockbrain.ai/docs

Before proceeding with the workflow, ensure you have:

1. Configured your Email Classification bot.

2. Defined and saved the classification ruleset in the E-Mail Classification prompt in the prompt library.

3. Selected the appropriate LLM model in the bot settings (for example GPT 5).

4. Retrieved your bot_id, agentTaskId as described in Section 4 of this guide.

2. API Basic Workflow

The process for classifying a single email consists of four main steps. It is strongly recommended to create a separate Data Room for each Email to maintain isolation between classifications and enable parallel processing.

Step 1 – Create Data Room

This operation creates a new conversation (Data Room) associated with your Email Classification bot.

• Endpoint: POST /cortex/active-bot/{bot_id}/convo

• API Reference: Create Data Room – API Documentation

Example request URL

https://blocky.theblockbrain.ai/cortex/active-bot/687e4c1b04e932e500e46c52/convo

Example request body

{
    "convoName": "Email_2025_08_21_001",  
    "sessionId": "68a70120d6167415e62a8074"  
}

Example response body

{
    "dataRoomId": "68de93f1fc203c550a278b09",
    "activeBotId": "68b968d3e8d7b4710f2b5632"
}

The response will contain a convoId that identifies this data room. This convoId is needed for the following steps.

Step 2 – Submit User (Email) Content

This operation sends the email text to the classification bot for processing.

• Endpoint: POST /cortex/completions/v2/user-input

• API Reference: Add User Messages – API Documentation

Example request URL

https://blocky.theblockbrain.ai/cortex/completions/v2/user-input

Example request body

{  
  "content": "Subject: Sample E-Mail Subject \n Body: Content of E-Mail.",  
  "actionType": "direct-agent",  
  "messageType": "user-question",  
  "sessionId": "68a70120d6167415e62a8074",  
  "convoId": "68a7277b804f80bd70b1c43f",  
  "agentTaskId": "68926547ce87314fbc4e500b"  
}

If enableStreaming is enabled, responses are returned token by token using Streaming. In that case, you may concatenate all returned new_token objects to form the final output.

Step 3 – Retrieve Classification Result

This operation retrieves the message detail through the messageId obtained as response in the previous step.

• Endpoint: GET /cortex/message/{message_id}

• API Reference: Get Message Detail - API Documentation

Example request URL

https://blocky.theblockbrain.ai/cortex/message/{message_id}

The classification result is the content of the response body, while the original sent message (E-Mail text) is targetText.

Alternatively you may get the complete message list

This operation retrieves the complete list of messages for a given conversation (convo_id).

• Endpoint: POST /cortex/message/list

• API Reference: Get Message List – API Documentation

Example request URL

https://blocky.theblockbrain.ai/cortex/message/list

Example request body

{  
  "convoId": "68a7277b804f80bd70b1c43f",  
  "sessionId": "68a70120d6167415e62a8074"  
}

Step 4 – Delete Data Room

This operation deletes the conversation (Data Room) to free resources and maintain a clean state.

• Endpoint: DELETE /cortex/conversation/{convo_id}

• API Reference: Delete Conversation – API Documentation

Example request URL

https://blocky.theblockbrain.ai/cortex/conversation/68a7277b804f80bd70b1c43

3. Best Practices

1. Create a new Data Room for each incoming email to avoid carrying over context from previous messages.

2. Use the prompt library to store classification prompts and ensure consistent use across UI and API.

3. Maintain separate API calls for each classification to keep workflows easy to trace.

4. Retrieving Necessary IDs

The following IDs are required for the API calls described in the workflow above.

Retrieving bot_id from the UI

1. Log in to Blockbrain and navigate to the Bot Creator in the UI.

2. Select your Email Classification Bot. The bot details will include a field named bot ID. This is the value used in the /cortex/active-bot/{bot_id}/convo call.

Generating sessionId

You will need to generate a random UUID from your client side and send it along with the request. You may use this sessionId for multiple API calls as shown in the workflow above and needn’t generate new sessionId for each.

Tip: You can also obtain a valid sessionId by logging in through the UI and then capturing it from the API requests in your browser’s developer tools. This is useful during initial testing because you can use that value directly when experimenting with API calls.

Retrieving agentTaskId

To access the complete list of agent tasks for your bot call: GET /cortex/active-bot/{bot_id} (API Reference:Get Active Bot Details – API Documentation ). The response will contain an array of Agent Tasks associated with the bot, including their id, name, and prompt details.

Tip: You can also obtain an agentTaskId by logging in through the UI and then capturing it from the API requests in your browser’s developer tools. The agentTaskId is unique for each selected prompt from the prompt library.

5. Working with Attachments

The best practice for integrating attachments into the conversation context is to upload the email attachment to the dataroom.

• Endpoint: POST /cortex/conversation/{convo_id}/attachment

• API Reference: Direct Upload Attachment – API Documentation

Example request URL

https://blocky.theblockbrain.ai/cortex/conversation/{convo_id}/attachment

Example request body

{  
  "sessionId": "68a70120d6167415e62a8074",
  "attachment": binary
}

Example Response

{
  "_id": "68b01c96171c0ebad995c6bf",
  "createdAt": "2025-08-28T09:08:38.071308",
  "modifiedAt": "2025-08-28T09:08:38.225527",
  "name": "API Guidance.pdf",
  "tokens": 0,
  "enabled": true,
  "errorMessage": null,
  "status": "IN_PROGRESS",
  "calculatedStatus": "IN_PROGRESS",
  "fileType": "TEXT",
  "url": null,
  "originUrl": null,
  "thumbUrl": null
}

Wait for Upload Completion

Before proceeding to the next workflow step, ensure the attachment(s) are successfully uploaded. The expected response structure is identical to the upload output. Poll until calculatedStatus = "SUCCESS" before continuing.

• Endpoint: GET /cortex/conversation/{convo_id}/attachment

• API Reference: Get Conversation Attachments – API Documentation

Example request URL

https://blocky.theblockbrain.ai/cortex/conversation/{convo_id}/attachment

Example response body

{
  "_id": "string",
  "createdAt": "2025-08-28T09:08:38.071308",
  "modifiedAt": "2025-08-28T09:08:38.225527",
  "name": "string",
  "tokens": 0,
  "enabled": true,
  "errorMessage": "string",
  "status": "IN_PROGRESS",
  "calculatedStatus": "SUCCESS",
  "fileType": "TEXT",
  "url": "string",
  "originUrl": "string",
  "thumbUrl": "string"
}

6. Working with Workflows

Best practice is to create a workflow in the UI and then trigger it via API. Workflows can also be created or updated programmatically using API calls such as create workflow step or update workflow step (Create & Update Workflow Step – API Documentation).

To execute a complete workflow via API

• Endpoint: POST /cortex/executor

• API Reference: Create Action Executor Workflow – API Documentation

Example request URL

https://blocky.theblockbrain.ai/cortex/executor

Example request body

{
    "messageId": "68af288a455921b14dd0456e",
    "workflowId": "687f45e8a8b31c9e80ac75bb",
    "attachmentId": null,
    "convoId": "68af288a455921b14dd0456d",
    "action": "continue_to_end",
    "wcpOwnerId": "string"
}

Example response body

{
    "code": 200,
    "key": "workflow-run-success",
    "body": {
        "convoId": "68af288a455921b14dd0456d",
        "runTaskId": "68b0218d9f14d16d889a80d7"
    }
}

Recommendation: Retrieve the workflowId from the UI (Developer Settings) rather than a dedicated API call. Best practice is to set the workflow to autopilot in the UI, so that all steps are automatically executed in sequence via API workflow. Select in this case action type “continue_to_end”.

Workflow modes

• Autopilot: Executes all steps automatically

• Human in the Loop: Requires user interaction between steps

Change Workflow Mode in the UI

1. In a data room, select workflows in the right side panel (Settings → Bot Settings → Workflows)

2. Select the workflow on the left-hand side

3. At the bottom-left of the workflow canvas, click Execution Mode and choose Autopilot.

4. Click Save

Get Detail Run Task ID

To retrieve the Step Id of each workflow step, use the Get Detail Run Task ID endpoint.

• Endpoint: GET cortex/executor/get-detail-run-task-by-id/{run_task_id}

• API Reference: Get Detail Run Task Id - API Documentation

Example Request URL

https://blocky.theblockbrain.ai/cortex/executor/get-detail-run-task-by-id/{run_task_id}

Example request body

{
  "runTaskId": "string",
}

Retrieve Results of a Specific Workflow Step

• Endpoint: GET /cortex/executor/get-workflow-step-output/{run_task_id}/{step_id}

• API Reference: Get Workflow Step Output - API Dcoumentation

Example Request URL

https://blocky.theblockbrain.ai/cortex/executor/get-workflow-step-output/{run_task_id}/{step_id}

The results of each step are found in the responseMessage - content field.

Example response body

{
  "stepOutput": {
    "_id": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "modifiedAt": "2019-08-24T14:15:22Z",
    "botId": "",
    "convoId": "",
    "convoName": "string",
    "runTaskId": "",
    "content": "string",
    "prompt": "string",
    "langfuseUrl": "",
    "messageId": "",
    "selectedWorkflowId": "",
    "selectedWorkflowStepId": "",
    "status": "success",
    "noteId": "string",
    "model": "gpt-3.5-turbo",
    "referMessageId": "",
    "referContent": "",
    "knowledgeBases": [
      "string"
    ],
    "stepContext": {
      "workflowId": "",
      "workflowStepId": "",
      "contexts": []
    },
    "error": "string",
    "webSearchQuery": "string",
    "webRef": [
      {
        "query": "string",
        "answer": []
      }
    ],
    "webProRef": [
      {
        "question": "string",
        "search_queries": []
      }
    ],
    "isWebProR": false,
    "webSearchConfig": {
      "webSearchProvider": "linkup_normal_web_search",
      "isLinkupDeepSearch": false
    },
    "responseMessage": {
      "_id": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "modifiedAt": "2019-08-24T14:15:22Z",
      "botId": "string",
      "userId": "string",
      "convoId": "string",
      "content": "string",
      …

Further useful API Endpoints for working with Workflows

Save Workflow Output to Dataroom:

• Endpoint: POST /cortex/executor/save-run-task-output

• API Reference: Save Run Task Output - API Documentation

Example Request URL

https://blocky.theblockbrain.ai/cortex/executor/save-workflow-step-output/{step_id}

Example request body

{
    "type": "convo",
    "convoId": "68af25b12c624d26822e059d",
    "runTaskId": "68af20caec137b44a2e03877"
}

The output can be saved in multiple formats; refer to the documentation for supported formats.

Run Workflow Step with Action:

This can be used to run individual steps or run workflows with human-in-the-loop, so that the whole workflow isn’t automatically executed.

• Endpoint: POST cortex/executor/run-step-with-action

• API Reference: Run Workflow Step in Action - API Documentation

Example Request URL

https://blocky.theblockbrain.ai/cortex/executor/run-step-with-action

Example request Body

{
  "runTaskId": "string",
  "stepId": "string",
  "action": ""continue_to_end"
}