Letter

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

Receiving Letters

Option 1: Importing letters as emails with attachments

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

The following steps are necessary to connect letters:

Connect the mailbox as described here: Connect 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 email address of the sender can be specified in the letter settings.
- The subject of the email contains only the word "LETTER". If you prefer a different keyword, this can be adapted in the letter settings.

Option 2: Importing letters via the REST API

When importing letters via the API, the channel attribute must be set to "letter". Enneo does 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 the ticket is saved — AI processing runs in the background. The difference is when it starts: with batch the ticket is queued and picked up by the next available worker; with realtime AI processing is triggered immediately in its own background process, without waiting in the queue — useful when a ticket should be processed as soon as possible; with false the ticket is created without any AI processing.
Attachments can either be uploaded as base64-encoded files via the base64 parameter or provided via a URL with 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

Enneo delivers a JSON object with the relevant information such as receiver, subject and text content, when a letter is to be shipped, to your usercode. From there, you can call a printing service of your choice via API.

This is configured under Settings -> Letters -> (Select mailbox) -> Webhooks -> Send letter.

Here is example code for sending letters:

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"
} catch (Exception 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

Enneo validates postal addresses to prevent letters from being sent to invalid addresses and returned as return post. These are described here: Address Validation

Using Addresses Stored in ERP