> For the complete documentation index, see [llms.txt](https://api.docs.blockbrain.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.docs.blockbrain.ai/integration-best-practices/email-classification.md). # 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:\ 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](https://blocky.theblockbrain.ai/redoc#tag/cortex-active-bot/operation/add_convo_to_bot_cortex_active_bot__bot_id__convo_post) Example request URL **`https://blocky.theblockbrain.ai/cortex/active-bot/687e4c1b04e932e500e46c52/convo`** Example request body ```json { "convoName": "Email_2025_08_21_001", "sessionId": "68a70120d6167415e62a8074" } ``` Example response body ```json { "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](https://blocky.theblockbrain.ai/redoc#tag/cortex-completions/operation/add_user_messages_cortex_completions_user_input_post) Example request URL **`https://blocky.theblockbrain.ai/cortex/completions/v2/user-input`** Example request body ```json { "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](/concepts/streaming.md). 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](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/get_message_detail_cortex_message__message_id__get) 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**:[ ](https://blocky.theblockbrain.ai/redoc#operation/getMessageById)[Get Message List – API Documentation](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/get_message_list_cortex_message_list_post) Example request URL **`https://blocky.theblockbrain.ai/cortex/message/list`** Example request body ```json { "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](https://blocky.theblockbrain.ai/redoc#tag/cortex-conversation/operation/delete_convo_cortex_conversation__convo_id__delete) 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](https://blocky.theblockbrain.ai/redoc#tag/cortex-active-bot/operation/get_active_bot_details_cortex_active_bot__bot_id__get)[ ](https://int.kb.theblockbrain.ai/bot/conversation/cortex/689c67f649f20adfffe2b526?doc_id=68a72abe1b34bdd1d0b171a5\&text_id=014f6991-4f0a-4640-a18b-087429220a27\&convoId=68a7294a0bb3266125158f9c\&messageId=68a73eda5ffd2c995fbec7e1\¤t=1755791141390)). 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](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/direct_upload_attachment_cortex_conversation__convo_id__attachment_post) Example request URL [https://blocky.theblockbrain.ai/cortex/conversation/{convo\_id}/attachment](https://blocky.theblockbrain.ai/cortex/conversation/%7Bconvo_id%7D/attachment) Example request body ```json { "sessionId": "68a70120d6167415e62a8074", "attachment": binary } ``` Example Response ```json { "_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](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/get_convo_attachments_cortex_conversation__convo_id__attachment_get)
Example request URL **`https://blocky.theblockbrain.ai/cortex/conversation/{convo_id}/attachment`** Example response body ```json { "_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](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/create_workflow_step_cortex_workflow_step_post)).
**To execute a complete workflow via API**
* **Endpoint**: POST /cortex/executor * **API Reference**: [Create Action Executor Workflow – API Documentation](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/create_action_executor_workflow_cortex_executor_post)
Example request URL **`https://blocky.theblockbrain.ai/cortex/executor`** Example request body ```json { "messageId": "68af288a455921b14dd0456e", "workflowId": "687f45e8a8b31c9e80ac75bb", "attachmentId": null, "convoId": "68af288a455921b14dd0456d", "action": "continue_to_end", "wcpOwnerId": "string" } ``` Example response body ```json { "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](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/get_detail_run_task_id_cortex_executor_get_detail_run_task_by_id__run_task_id__get) Example Request URL **`https://blocky.theblockbrain.ai/cortex/executor/get-detail-run-task-by-id/{run_task_id}`** Example request body ```json { "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](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/get_workflow_step_output_cortex_executor_get_workflow_step_output__run_task_id___step_id__get) 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 ```json { "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](https://blocky.theblockbrain.ai/redoc#tag/cortex-executor/operation/save_workflow_step_output_cortex_executor_save_workflow_step_output__step_id__post) Example Request URL **`https://blocky.theblockbrain.ai/cortex/executor/save-workflow-step-output/{step_id}`** Example request body ```json { "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](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/run_workflow_step_with_action_cortex_executor_run_step_with_action_post)
Example Request URL **`https://blocky.theblockbrain.ai/cortex/executor/run-step-with-action`** Example request Body ```json { "runTaskId": "string", "stepId": "string", "action": ""continue_to_end" } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://api.docs.blockbrain.ai/integration-best-practices/email-classification.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.