Skip to main content
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:
  1. Connect the mailbox as described here: Connect Emails
  2. 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

  1. When importing letters via the API, the channel attribute must be set to “letter”. Enneo does the rest.
  2. 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

​
Sending letters

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

Instead of the sender identified by AI, Enneo can also reply to a postal address you have stored. For this, the variable letterAddress must be set in the Response Format of the Contract Data, e.g. "letterAddress": "Laura Ludwig, Main Street 29, 20249 Hamburg".