Letter

Just like emails, letters can also be connected in enneo in two ways, depending on the requirements: IMAP and API.

Receipt of Letters

Option 1: Import of Letters as E-mail with Attachment

This solution is recommended if a scanning service is used, which converts incoming letters into emails with the letters as an attachment (e.g., PDF).

To connect letters, the following steps are necessary:

Connect the mailbox as described here: Connecting emails
Ensure that the emails are recognized as letters. Enneo recognizes an email as a letter if the following criteria are met:
- The sender of the email is the scanning service. The sender's email address can be specified in the letter settings.
- The subject of the email contains only the word "LETTER". If a different keyword is preferred, this can be adjusted in the letter settings.

Option 2: Import of Letters via the REST API

When importing letters via the API, the channel attribute must be set to "letter". Enneo will handle the rest.
An example of a request with minimal parameters:

curl --location 'https://demo.enneo.ai/api/mind/ticket' \
--header 'Authorization: bearer <token>' \
--data '{
    "channel": "letter",
    "process": "batch",
    "attachments": [
        {
            "base64": "base-64-encoded-string-of-pdf-or-image-file",
        }
    ]
}

Notes:

The process parameter can be set to batch (default), realtime, or false. In all cases, the API response returns immediately after saving the ticket - AI processing is running in the background. The difference is when it starts: With batch, the ticket is queued for normal processing and is handled by the next available worker. With realtime, AI processing is initiated immediately in its own background process, without waiting in the queue - useful if a ticket should preferably be processed immediately. With false, the ticket is created without AI processing.
Attachments can either be uploaded as Base64-encoded files via the base64 parameter or provided via a URL using the url parameter.
All ticket attributes defined in the API specification can also be specified. This is useful for transmitting metadata such as a contract ID, tags, or a creation date.

Supported File Formats

Enneo supports the automatic conversion of attachments in the following formats:

PDF
PNG
JPG
TIFF

When a letter is to be sent, enneo passes a JSON object with the relevant data - such as recipient, subject, and text content - to the respective user code. From there, they can call a printing service of their choice via API.

This can be configured under Settings -> Letters -> (Select mailbox) -> Webhooks -> Send letter

Here is example code for sending a letter:

import importlib.util
import os
import json

file_path = os.getenv("SDK", "sdk.py")
spec = importlib.util.spec_from_file_location("sdk", file_path)
sdk = importlib.util.module_from_spec(spec)
spec.loader.exec_module(sdk)

input_data = sdk.load_input_data()
ticket_id = input_data.get("ticketId")

# Optional: load ticket data if you need it elsewhere
ticket_data = sdk.ApiEnneo.get(f"/api/mind/ticket/{ticket_id}")

# Build payload from input_data
payload = {
    "to": input_data.get("to"),
    "subject": input_data.get("subject"),
    "body": input_data.get("body"),
    "attachments": input_data.get("attachments", []),
    "userId": input_data.get("userId"),
    "ticketId": ticket_id,
    "conversationId": input_data.get("conversationId", ""),
    "contractId": input_data.get("contractId"),
    "customerId": input_data.get("customerId"),
    "subchannelId": input_data.get("subchannelId", ""),
}

try:
    echo_response = sdk.Api.call(
        method="POST",
        url="https://echo.enneo.ai/api/echo", # replace with your printing service here
        headers={},
        params=payload,
    )
    output_msg = "Letter sent successfully"
except Exception as e:
    print(json.dumps({"input": input_data, "error": str(e)}))
    exit(1)

print(json.dumps({
    "input": input_data,
    "payloadSentToEcho": payload,
    "echoResponse": echo_response,
    "output": output_msg,
}))

Validation of Postal Addresses

Postal addresses are validated so that no letters are sent to invalid addresses and returned as postal returns. These are described here: Address Validation

Use of Addresses Stored in ERP