> 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/de/best-practices-fur-integrationen/e-mail-klassifizierung.md). # E-Mail-Klassifizierung ### 1. Einleitung Der vorgesehene Anwendungsfall ist, eingehende E-Mails gemäß einem vordefinierten Regelsatz zu klassifizieren. Die Klassifizierungslogik wird in der Blockbrain-UI konfiguriert und kann für Automatisierungszwecke über die API aufgerufen werden. Alle in der UI verfügbaren Funktionen sind auch über die API zugänglich. Die UI sollte verwendet werden, um den Klassifizierungs-Bot und seinen Prompt einzurichten, während die API für die Implementierung automatisierter oder groß angelegter Workflows genutzt werden sollte. Die vollständige Blockbrain-API-Dokumentation finden Sie hier:\ Bevor Sie mit dem Workflow fortfahren, stellen Sie sicher, dass Sie Folgendes haben: 1. **Ihren E-Mail-Klassifizierungs-Bot konfiguriert.** 2. **Den Klassifizierungs-Regelsatz im Prompt „E-Mail Classification“ in der Prompt-Bibliothek definiert und gespeichert.** 3. **Das passende LLM-Modell in den Bot-Einstellungen ausgewählt (zum Beispiel GPT 5).** 4. **Ihre `bot_id`sowie die agentTaskId wie in Abschnitt 4 dieses Leitfadens beschrieben abgerufen.** ### 2. Grundlegender API-Workflow Der Prozess zur Klassifizierung einer einzelnen E-Mail besteht aus vier Hauptschritten. Es wird dringend empfohlen, für jede E-Mail einen separaten Data Room anzulegen, um die Isolierung zwischen Klassifizierungen zu gewährleisten und parallele Verarbeitung zu ermöglichen. #### **Schritt 1 – Data Room erstellen** Dieser Vorgang erstellt eine neue Konversation (Data Room), die mit Ihrem E-Mail-Klassifizierungs-Bot verknüpft ist. * **Endpunkt**: POST /cortex/active-bot/{bot\_id}/convo * **API-Referenz**:[ Data Room erstellen – API-Dokumentation](https://blocky.theblockbrain.ai/redoc#tag/cortex-active-bot/operation/add_convo_to_bot_cortex_active_bot__bot_id__convo_post) Beispiel-Request-URL **`https://blocky.theblockbrain.ai/cortex/active-bot/687e4c1b04e932e500e46c52/convo`** Beispiel-Request-Body ```json { "convoName": "Email_2025_08_21_001", "sessionId": "68a70120d6167415e62a8074" } ``` Beispiel-Response-Body ```json { "dataRoomId": "68de93f1fc203c550a278b09", "activeBotId": "68b968d3e8d7b4710f2b5632" } ``` Die Antwort enthält eine `convoId` , die diesen Data Room identifiziert. Diese `convoId` wird für die folgenden Schritte benötigt. #### **Schritt 2 – Benutzerinhalt (E-Mail) übermitteln** Dieser Vorgang sendet den E-Mail-Text zur Verarbeitung an den Klassifizierungs-Bot. * **Endpunkt**: POST /cortex/completions/v2/user-input * **API-Referenz**: [Benutzernachrichten hinzufügen – API-Dokumentation](https://blocky.theblockbrain.ai/redoc#tag/cortex-completions/operation/add_user_messages_cortex_completions_user_input_post) Beispiel-Request-URL **`https://blocky.theblockbrain.ai/cortex/completions/v2/user-input`** Beispiel-Request-Body ```json { "content": "Betreff: Beispiel-E-Mail-Betreff \n Inhalt: Inhalt der E-Mail.", "actionType": "direct-agent", "messageType": "user-question", "sessionId": "68a70120d6167415e62a8074", "convoId": "68a7277b804f80bd70b1c43f", "agentTaskId": "68926547ce87314fbc4e500b" } ``` Falls **`enableStreaming`** aktiviert ist, werden Antworten Token für Token mit [Streaming](/de/konzepte/streaming.md)zurückgegeben. In diesem Fall können Sie alle zurückgegebenen new\_token-Objekte verketten, um die finale Ausgabe zu bilden. #### **Schritt 3 – Klassifizierungsergebnis abrufen** Dieser Vorgang ruft die Nachrichtendetails über die messageId ab, die im vorherigen Schritt als Antwort erhalten wurde. * **Endpunkt**: GET /cortex/message/{message\_id} * **API-Referenz**: [Nachrichtendetails abrufen – API-Dokumentation](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/get_message_detail_cortex_message__message_id__get) Beispiel-Request-URL **`https://blocky.theblockbrain.ai/cortex/message/{message_id}`** Das Klassifizierungsergebnis ist der **`content`** des Response-Bodys, während die ursprünglich gesendete Nachricht (E-Mail-Text) **`targetText`**. **ist. Alternativ können Sie die vollständige Nachrichtenliste abrufen** Dieser Vorgang ruft die vollständige Liste der Nachrichten für eine bestimmte Konversation (convo\_id) ab. * **Endpunkt**: POST /cortex/message/list * **API-Referenz**:[ ](https://blocky.theblockbrain.ai/redoc#operation/getMessageById)[Nachrichtenliste abrufen – API-Dokumentation](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/get_message_list_cortex_message_list_post) Beispiel-Request-URL **`https://blocky.theblockbrain.ai/cortex/message/list`** Beispiel-Request-Body ```json { "convoId": "68a7277b804f80bd70b1c43f", "sessionId": "68a70120d6167415e62a8074" } ``` #### **Schritt 4 – Data Room löschen** Dieser Vorgang löscht die Konversation (Data Room), um Ressourcen freizugeben und einen sauberen Zustand beizubehalten. * **Endpunkt**: DELETE /cortex/conversation/{convo\_id} * **API-Referenz**:[ Konversation löschen – API-Dokumentation](https://blocky.theblockbrain.ai/redoc#tag/cortex-conversation/operation/delete_convo_cortex_conversation__convo_id__delete) Beispiel-Request-URL **`https://blocky.theblockbrain.ai/cortex/conversation/68a7277b804f80bd70b1c43`** ### 3. Best Practices 1. Erstellen Sie für jede eingehende E-Mail einen neuen Data Room, um die Übernahme von Kontext aus vorherigen Nachrichten zu vermeiden. 2. Verwenden Sie die Prompt-Bibliothek, um Klassifizierungs-Prompts zu speichern und eine konsistente Nutzung über UI und API hinweg sicherzustellen. 3. Führen Sie separate API-Aufrufe für jede Klassifizierung durch, um Workflows leicht nachvollziehbar zu halten. ### 4. Abrufen der erforderlichen IDs Die folgenden IDs werden für die oben im Workflow beschriebenen API-Aufrufe benötigt. #### **Abrufen `bot_id` aus der UI** 1. Melden Sie sich bei Blockbrain an und navigieren Sie in der **Bot Creator** in der UI. 2. Wählen Sie Ihren **E-Mail-Klassifizierungs-Bot**. Die Bot-Details enthalten ein Feld namens **`bot ID`**. Dies ist der Wert, der im **`/cortex/active-bot/{bot_id}/convo`** Aufruf verwendet wird.
#### **sessionId generieren** Sie müssen eine **zufällige UUID** auf Ihrer Client-Seite generieren und zusammen mit der Anfrage senden. Sie *können diese sessionId für mehrere API-Aufrufe verwenden* wie im obigen Workflow gezeigt und müssen nicht für jeden Aufruf eine neue sessionId generieren. **Tipp**: Sie können eine gültige **`sessionId`** auch erhalten, indem Sie sich über die UI anmelden und sie dann aus den API-Anfragen in den Entwicklertools Ihres Browsers auslesen. Dies ist beim ersten Testen nützlich, da Sie diesen Wert direkt beim Experimentieren mit API-Aufrufen verwenden können. #### agentTaskId abrufen Um die vollständige Liste der Agent-Aufgaben für Ihren Bot aufzurufen, verwenden Sie:\ GET **`/cortex/active-bot/{bot_id}`** (**API-Referenz**:[Aktive Bot-Details abrufen – API-Dokumentation](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)). Die Antwort enthält ein Array von Agent Tasks, die dem Bot zugeordnet sind, einschließlich ihrer ID, ihres Namens und der Prompt-Details. **Tipp**: Sie können auch eine **`agentTaskId`** erhalten, indem Sie sich über die UI anmelden und sie dann aus den API-Anfragen in den Entwicklertools Ihres Browsers auslesen. Die agentTaskId ist für jeden ausgewählten Prompt aus der Prompt-Bibliothek eindeutig. ### 5. Arbeiten mit Anhängen Die beste Vorgehensweise zur Einbindung von Anhängen in den Gesprächskontext ist, den E-Mail-Anhang in den Dataraum hochzuladen.
* **Endpunkt**: POST /cortex/conversation/{convo\_id}/attachment * **API-Referenz**: [Anhang direkt hochladen – API-Dokumentation](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/direct_upload_attachment_cortex_conversation__convo_id__attachment_post) Beispiel-Request-URL [https://blocky.theblockbrain.ai/cortex/conversation/{convo\_id}/attachment](https://blocky.theblockbrain.ai/cortex/conversation/%7Bconvo_id%7D/attachment) Beispiel-Request-Body ```json { "sessionId": "68a70120d6167415e62a8074", "attachment": binary } ``` Beispielantwort ```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 } ``` #### Warten Sie auf den Abschluss des Uploads Stellen Sie vor dem Fortfahren mit dem nächsten Workflow-Schritt sicher, dass der/die Anhang/Anhänge erfolgreich hochgeladen wurden. Die erwartete Antwortstruktur ist identisch mit der Upload-Ausgabe. Fragen Sie wiederholt ab, bis calculatedStatus = "SUCCESS" ist, bevor Sie fortfahren.
* **Endpunkt**: GET /cortex/conversation/{convo\_id}/attachment * **API-Referenz**: [Konversationsanhänge abrufen – API-Dokumentation](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/get_convo_attachments_cortex_conversation__convo_id__attachment_get)
Beispiel-Request-URL **`https://blocky.theblockbrain.ai/cortex/conversation/{convo_id}/attachment`** Beispiel-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. Arbeiten mit Workflows Die beste Vorgehensweise ist, einen Workflow in der UI zu erstellen und ihn dann über die API auszulösen. Workflows können auch programmatisch mit API-Aufrufen wie create workflow step oder update workflow step erstellt oder aktualisiert werden ([Workflow-Schritt erstellen und aktualisieren – API-Dokumentation](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/create_workflow_step_cortex_workflow_step_post)).
**Um einen vollständigen Workflow über die API auszuführen**
* **Endpunkt**: POST /cortex/executor * **API-Referenz**: [Action Executor Workflow erstellen – API-Dokumentation](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/create_action_executor_workflow_cortex_executor_post)
Beispiel-Request-URL **`https://blocky.theblockbrain.ai/cortex/executor`** Beispiel-Request-Body ```json { "messageId": "68af288a455921b14dd0456e", "workflowId": "687f45e8a8b31c9e80ac75bb", "attachmentId": null, "convoId": "68af288a455921b14dd0456d", "action": "continue_to_end", "wcpOwnerId": "string" } ``` Beispiel-Response-Body ```json { "code": 200, "key": "workflow-run-success", "body": { "convoId": "68af288a455921b14dd0456d", "runTaskId": "68b0218d9f14d16d889a80d7" } } ``` **Empfehlung**: Rufen Sie die workflowId aus der UI (Entwicklereinstellungen) ab und nicht über einen dedizierten API-Aufruf. Best Practice ist, den Workflow in der UI auf Autopilot zu setzen, damit alle Schritte automatisch nacheinander über den API-Workflow ausgeführt werden. Wählen Sie in diesem Fall den Aktionstyp „continue\_to\_end“.
**Workflow-Modi** * **Autopilot**: Führt alle Schritte automatisch aus * **Human in the Loop**: Erfordert Benutzerinteraktion zwischen den Schritten
**Workflow-Modus in der UI ändern** 1. Wählen Sie in einem Data Room Workflows im rechten Seitenpanel aus (Einstellungen → Bot-Einstellungen → Workflows) 2. Wählen Sie den Workflow auf der linken Seite aus 3. Klicken Sie unten links im Workflow-Canvas auf Execution Mode und wählen Sie Autopilot aus. 4. Klicken Sie auf Speichern
**Detail-Run-Task-ID abrufen** Um die Step Id jedes Workflow-Schritts abzurufen, verwenden Sie den Endpunkt Get Detail Run Task ID. * **Endpunkt:** GET cortex/executor/get-detail-run-task-by-id/{run\_task\_id} * **API-Referenz**:[ Detail Run Task Id abrufen – API-Dokumentation](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) Beispiel-Request-URL **`https://blocky.theblockbrain.ai/cortex/executor/get-detail-run-task-by-id/{run_task_id}`** Beispiel-Request-Body ```json { "runTaskId": "string", } ``` **Ergebnisse eines bestimmten Workflow-Schritts abrufen** * Endpunkt: GET **`/cortex/executor/get-workflow-step-output/{run_task_id}/{step_id}`** * API-Referenz: [Workflow-Schritt-Ausgabe abrufen – API-Dokumentation](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/get_workflow_step_output_cortex_executor_get_workflow_step_output__run_task_id___step_id__get) Beispiel-Request-URL **`https://blocky.theblockbrain.ai/cortex/executor/get-workflow-step-output/{run_task_id}/{step_id}`** Die Ergebnisse jedes Schritts befinden sich im Feld responseMessage - content. Beispiel-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", … ``` **Weitere nützliche API-Endpunkte für die Arbeit mit Workflows** Workflow-Ausgabe im Dataroom speichern: * **Endpunkt**: POST **`/cortex/executor/save-run-task-output`** * **API-Referenz**: [Run Task Output speichern – API-Dokumentation](https://blocky.theblockbrain.ai/redoc#tag/cortex-executor/operation/save_workflow_step_output_cortex_executor_save_workflow_step_output__step_id__post) Beispiel-Request-URL **`https://blocky.theblockbrain.ai/cortex/executor/save-workflow-step-output/{step_id}`** Beispiel-Request-Body ```json { "type": "convo", "convoId": "68af25b12c624d26822e059d", "runTaskId": "68af20caec137b44a2e03877" } ``` Die Ausgabe kann in mehreren Formaten gespeichert werden; entnehmen Sie die unterstützten Formate der Dokumentation. Workflow-Schritt mit Aktion ausführen:
Dies kann verwendet werden, um einzelne Schritte oder Workflows mit Human-in-the-Loop auszuführen, sodass der gesamte Workflow nicht automatisch ausgeführt wird.
* **Endpunkt**: POST **`cortex/executor/run-step-with-action`** * **API-Referenz**:[ Workflow-Schritt mit Aktion ausführen – API-Dokumentation](https://blocky.theblockbrain.ai/redoc#tag/cortex/operation/run_workflow_step_with_action_cortex_executor_run_step_with_action_post)
Beispiel-Request-URL **`https://blocky.theblockbrain.ai/cortex/executor/run-step-with-action`** Beispiel-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/de/best-practices-fur-integrationen/e-mail-klassifizierung.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.