Skip to main content
Just like emails, letters can also be integrated into Enneo in two ways, depending on the requirements: IMAP and API.

​
Receiving Letters

​
Option 1: Importing letters as emails with an attachment

This solution is recommended when a scan service is used that converts incoming letters into emails with the letters as attachments (e.g., PDF). To integrate letters, the following steps are necessary:
  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 scan service. The email address of the sender can be specified in the letter settings.
    • The subject of the email exclusively contains the word “LETTER”. If a different keyword is preferred, it can be adjusted in the letter settings.

​
Option 2: Import of letters via the REST API

  1. When importing letters via the API, the channel attribute must be set to “letter”. Enneo takes care of the rest.
  2. Here is 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 either to batch (default) or realtime. With realtime, the letter is processed instantly, not asynchronously, by the AI, which can cause the request to take a bit longer.
  • Attachments can be uploaded either as Base64-encoded files via the base64 parameter or provided through a URL using the url parameter.
  • All ticket attributes defined in the API specification can also be included. This is helpful 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

When a letter needs to be sent, Enneo passes a JSON object with relevant data such as recipient, subject, and text content to your user code. From there, you can call a print service provider of your choice via the API. This can be configured under Settings -> Letters -> (Select mailbox) -> Webhooks -> Send letter Here is sample 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

Enneo validates postal addresses to ensure that no letters are sent to invalid addresses and returned as returned mail. These are described here: Address Validation

​
Usage of addresses stored in ERP

Enneo can reply to a postal address provided by you rather than the sender identified by the AI. In the Response Format of Contract Data, the letterAddress variable must be set, e.g. "letterAddress": "Laura Ludwig, Hauptstraße 29, 20249 Hamburg"