HCL Domino · LLM · OpenAI · API-Engine
LLM-Based E-Mail Classification in HCL Domino
Modern Large Language Models can do much more than generate text. They can evaluate structured data, classify content and return results in a defined format. With the SL Net-Solutions Domino API-Engine, such a service can be integrated directly into a server-side Domino process.
A new example included in the API-Engine Evaluation Package demonstrates this using a practical scenario: e-mails are read from a Domino database, including relevant RFC822 headers and MIME content, submitted to the OpenAI Responses API via HTTPS and subsequently classified directly within Domino.
No additional middleware is required to access the LLM service. The API-Engine creates the JSON request, performs the HTTPS call, processes the structured JSON response and writes the result back to the original Domino document.
Practical Example
Spam Score, Classification and Summary
The OPENAI_TEST example script processes e-mail documents from a Domino database and submits the information relevant to the evaluation to a Large Language Model.
The model receives mail headers, authentication information and the actual message content. Structured Outputs are used to restrict the response to a predefined JSON schema.
LLMSpamRating
A score from 0 to 100. A low value indicates a probably legitimate message, while a high value indicates a strong likelihood of spam.
LLMCategory
Assignment to exactly one of the categories Advertising, Spam, Malware or Correspondence.
LLMSummary
A short factual summary of the message content, regardless of the language of the original e-mail.
{
"score": 92,
"category": "Malware",
"summary": "Suspicious invoice e-mail containing an HTML attachment and indicators of phishing."
}Processing Flow
From a Domino Document to a Structured LLM Response
The entire processing flow takes place within the server-side API-Engine process. Domino data does not first have to be exported through a separate application or middleware service.
Technical Workflow
What the Test Script Actually Does
The API-Engine searches for mail documents that have not yet received an LLM-based evaluation.
Relevant headers and the message body are processed directly from the Domino document.
The request for the OpenAI Responses API is constructed as a JSON structure directly within the API-Engine script.
The API-Engine communicates directly with the external REST service. No additional proxy or custom middleware service is required for the example.
The model returns the classification according to a predefined JSON schema.
Score, category and summary are written directly as items into the original Domino document.
Structured Outputs
An LLM Result That Can Be Reliably Processed
For automated processing, a freely formulated response from a language model is often not sufficient. The example therefore uses a predefined JSON schema.
This ensures, for example, that the spam score is an integer between 0 and 100 and that the category contains only one of the permitted values.
{
"type": "object",
"properties": {
"score": {
"type": "integer",
"minimum": 0,
"maximum": 100
},
"category": {
"type": "string",
"enum": [
"Advertising",
"Spam",
"Malware",
"Correspondence"
]
},
"summary": {
"type": "string"
}
},
"required": [
"score",
"category",
"summary"
],
"additionalProperties": false
}The response can therefore be processed like any other structured interface response. The language model is not used as an interactive chat system, but as a component of an automated data-processing workflow.
Mail Analysis
More Than Just the Visible Message Text
A meaningful evaluation can include more than the visible content of an e-mail. Technical mail headers can also provide useful information.
SPF, DKIM and DMARC
Successful authentication results can be considered positive indicators during the evaluation.
From and Envelope-From
Differences between sender information are taken into account, but are not automatically treated as an indication of spam.
MIME and Message Content
Links, wording, advertising content and other characteristics can be evaluated together with the technical information.
LLM Security
E-Mail Content Is Data, Not Instructions
Whenever untrusted content is submitted to a language model, that content itself may contain instructions intended to influence the model.
The example therefore explicitly instructs the model to treat all e-mail content exclusively as data to be analyzed and never as instructions.
This separation is particularly important in automated LLM workflows. The message itself must not determine how the model executes the higher-level analysis task.
Important Limitation
A Classification Example – Not a Replacement for Antivirus Software
In this example, the Malware category describes messages whose content, links, headers or other recognizable characteristics indicate phishing, malicious software or an attempt to compromise credentials or systems.
The example does not perform technical malware analysis of file attachments. It therefore does not replace antivirus software or a specialized mail-security gateway.
The script is deliberately designed as a technical evaluation example. Depending on the environment, production use would additionally require appropriate error handling, logging, rate-limit handling, data-protection considerations, secure API-key management and other security measures.
Integration
Why This Example Is Relevant for Domino
The main point of the example is not merely the classification of an e-mail. It demonstrates how modern REST and AI services can be integrated into existing Domino processes without moving the actual processing out of Domino.
Data Remains Part of the Domino Process
NSF documents can be read directly, processed and updated again after the external API call.
Call External APIs Directly
HTTP, HTTPS and JSON can be handled within the same API-Engine process.
Automated Background Processing
The same approach can be applied to large numbers of Domino documents using time-, event- or process-controlled execution.
Domino IQ
How Does This Relate to Domino IQ?
Starting with HCL Domino 14.5, Domino IQ provides native integration of Large Language Models into the Domino platform. Applications can submit generative AI requests through Domino using the NotesLLMRequest and NotesLLMResponse LotusScript classes.
The API-Engine example presented here takes a different approach. It communicates directly with the OpenAI Responses API using HTTPS and JSON. The purpose of the example is therefore not to replace Domino IQ, but to demonstrate how external AI and REST services can be integrated directly into an API-Engine processing workflow.
Native AI Integration in Domino
Domino IQ provides an AI inference layer integrated into current Domino versions and makes LLM functionality available to Domino applications through dedicated APIs.
Direct Integration with External APIs
The API-Engine can communicate directly with external REST services and combine those calls with NSF, MIME, RFC822, JSON, SQL and other processing within the same workflow.
Also Relevant for Older Domino Environments
The OPENAI_TEST example runs on HCL Domino 10 and later and therefore does not require a Domino version that provides Domino IQ.
The two approaches are not mutually exclusive. Domino IQ provides a native AI layer for modern Domino environments, while the API-Engine remains useful wherever direct control over external APIs, data preparation and subsequent processing is required.
Evaluation Package
Try the Example Yourself
The current API-Engine V12.12 Evaluation Package includes the complete OPENAI_TEST example script.
OPENAI_TEST
The example demonstrates processing RFC822 and MIME data, constructing a JSON request, directly calling the OpenAI Responses API via HTTPS, using Structured Outputs, and processing and storing the resulting data in Domino.
The example runs on HCL Domino 10 and later. It is also expected to work with Domino 9, although this has not been explicitly tested.
Conclusion
LLMs as Another Building Block for Domino Processes
Large Language Models do not have to exist as separate applications alongside Domino. Like other external services, they can become part of an automated Domino process.
The API-Engine handles the technical integration: reading Domino data, generating JSON, performing HTTPS requests, processing responses and making the resulting data directly available in Domino again.
The e-mail example is only one possible use case. The same approach can also be used for document classification, data extraction, summarization, text analysis or structured processing of business documents.