Customization

Custom Incoming Message Webhook Task

When a new email arrives at EmailEngine, a webhook will be sent to the email integration to handle it. The handling is executed in a task that could be overriden by a custom one using Application Config.

Getting Started

1. Generate a new task in your solution using Lime Project.
2. Register the task to override the standard incoming webhook task by adding it to the Optional Application Configuration.

Example Webhook Data

The webhook for an incoming message looks something like below, and the most relevant information is probably in the data property.

{
  "serviceUrl": "http://localhost:3000",
  "account": "2g3u4q8y450j5y0n",
  "date": "2024-09-05T12:39:45.744Z",
  "path": "INBOX",
  "specialUse": "\\Inbox",
  "event": "messageNew",
  "data": {
    "id": "AAAAAQAACLY",
    "uid": 2230,
    "path": "INBOX",
    "date": "2024-09-05T12:39:38.000Z",
    "flags": [],
    "unseen": true,
    "size": 66202,
    "subject": "Want to buy a pizza [1234]",
    "from": { "name": "Kim Young", "address": "[email protected]" },
    "to": [
      {
        "name": "Support",
        "address": "[email protected]"
      }
    ],
    "messageId": "<AS8PR08MB89955D313A2F291643AD9E6C9R2D2@AS8PR08MB8995.japrd368.prof.inlook.com>",
    "text": {
      "id": "AAAAAQAACLaTkaExkaEykA",
      "encodedSize": { "plain": 31, "html": 1300 }
    },
    "specialUse": "\\Inbox",
    "messageSpecialUse": "\\Inbox",
    "seemsLikeNew": true
  }
}

Note

data.id and account are the internal EmailEngine ids that needs to be passed to the standard email integration import function. data.messageId is the global unique Message-ID. The text/html of the message is not included for performance reasons.

Example: Pizza Handler

For the solution "Pizza", a new task called incoming was created. It's purpose is to filter out emails containing the word "pizza" in the subject. These should not result in conversations, but rather just create history notes. If no "pizza" is present in the subject, the standard function import_message() that imports messages will be used instead.

Application Configuration

In the Application Configuration, the following parameter was added:

incoming_message_webhook_task: solution_pizza.tasks.tasks.incoming

Task Code

solution-pizza/solution_pizza/tasks/tasks.py

from lime_task import task
from limepkg_email.message_service.incoming import import_message

import logging


logger = logging.getLogger(__name__)


@task
def incoming(app, payload):
    if "pizza" in payload["data"]["subject"]:
        logger.info("Found pizza in subject, creating history note")

        history = app.limetypes.history()
        history.properties.type.set_by_key("comment")
        history.properties.note.value = (
            f'{payload["data"]["from"]["name"]} wants to buy a pizza!'
        )
        uow = app.unit_of_work()
        uow.add(history)
        uow.commit()
    else:
        logger.info("No pizza present in subject, starting normal import")

        import_message(
            app,
            payload["data"]["id"],
            payload["account"],
        )

Trying It Out

1. Restart the task handler after every code change.
2. Send an email with the word "pizza" in the subject and expect a history note to be created.
3. Send an email without "pizza" in the subject and expect a conversation message to be created.