<!--
SPDX-FileCopyrightText: 2026 Jan Maarten van Doorn <laelaps@vandoorn.cloud>

SPDX-License-Identifier: MPL-2.0
-->

# Laelaps

Laelaps is an IMAP monitoring application that is capable of verifying signed aliases. This is particularly useful when using different catchall-based aliases. Catchall-based aliases are a convenient way to generate unique email addresses for online accounts and reduce the impact of potential data leaks. However with catchall mode turned on there is a risk of attracting lots of spam.

Laelaps solves this problem by verifying whether an alias is indeed generated by the user and not by some other random party such as a spammer. This is achieved without registering the known aliases by using cryptographic signatures within generated aliases themselves. In practice a user generates an alias using a private key and the [TeumessianFox](https://github.com/Marmalade8478/TeumessianFox) browser extension and Lealaps will separate spam from emails that are send to genuine aliases. This way the user can easily generate new aliases and still be in full control of messages send to her/his inbox.

As a bonus, albeit rather experimental, Laelaps can perform other checks on incoming email messages by analyzing the message headers, these checks include:

- Verifying whether SPF, DMARC and DKIM passed.
- Possibility to register an aliases for a specific domain that is allowed to send messages only to this specific alias.
- Check wether the email was send with TLS enabled
- Check wether the sending email address exists

Laelaps moves incoming messages either to an inbox folder for messages that passed validation or to a folder that failed validation.

## Install

### Install from pypi

```shell
pip install laelaps
```


### Setting up with UV for local development

1. **Create a virtual environment**:

```shell
uv venv .venv
source .venv/bin/activate
```

2. **Install dependencies**:

```shell
uv pip sync pyproject.toml
```

To include test/dev dependencies:

```shell
uv pip sync --extra test pyproject.toml
```

## Configure

Create a `config.toml` with the following contents in your working directory:

```toml
[imap]
host = "your.imap.server.host"
username = "yourImapUserName"
password = "ImapPassword"
mailbox = "FolderToMonitor"

[encryption]
# Generate yourself and keep safe!
key = "32CharacterStringEncryptionKey00"

[user]
own_domains = [ "list.of", "catchall.domains"]
target_folder_verified = "FolderToForVerifiedEmails"
target_folder_failed_validation = "FolderToForFailedVerificationEmails"
```

### Configuring using environment variables

When running Laelaps in a container, it may be useful to configure it using environment variables. If the configuration file cannot be found Laelqaps will look for the following variables:

```shell
LAELAPS_IMAP__HOST=your.imap.server.host
LAELAPS_IMAP__MAILBOX=FolderToMonitor
LAELAPS_IMAP__USERNAME=yourImapUserName
LAELAPS_IMAP__PASSWORD=ImapPassword
LAELAPS_USER__OWN_DOMAINS=list.of,own.domains
LAELAPS_USER__TARGET_FOLDER_VERIFIED=FolderToForVerifiedEmails
LAELAPS_USER__TARGET_FOLDER_FAILED_VALIDATION=FolderToForFailedVerificationEmails
LAELAPS_ENCRYPTION__KEY=32CharacterStringEncryptionKey00
```

## Run

Start laelaps with:

```shell
python -m laelaps
```

Stop laelaps with
<kbd>ctrl</kbd>+<kbd>C</kbd>

### Run with Docker
Make sure to have a configuration ready.

From the root of the repository run
```shell
docker compose up
```

