Overview

Signaturmonster — Documentation

Signaturmonster is a self-hosted SMTP proxy that sits between your email client (e.g. Thunderbird) and the outgoing mail server. It intercepts every outgoing email and automatically enriches it with HTML signatures, corporate identity branding and animated GIF banners — without any changes to the email client or mail server.

Architecture

Signaturmonster consists of five Docker containers running as a Compose stack:

# Incoming from email client
Thunderbird / Outlook
       │
       ▼ Port 587
SMTP Proxy       # Python / aiosmtpd — intercepts mails, injects signature
       │
       ▼ internal
Backend API      # FastAPI + SQLite — signatures, rules, CI profiles
       │
       ├─ Frontend    # React + nginx — web UI on port 8080
       │
       └─ Updater     # Checks ghcr.io for new versions
       │
       ▼ Forwarded
Real mail servers (SMTP, port 465/587)

Requirements

Requirements

To run Signaturmonster you need:

• Docker ≥ 24 and Docker Compose ≥ 2.20
• A device on the local network with at least 512 MB RAM and Docker support
• An outgoing SMTP server (e.g. Gmail SMTP, Postfix, Hetzner Mail, your own server)
• Port 587 free on the host or configurable
• Port 8080 for the web UI reachable on the local network (can be changed)

Check Docker version

docker --version
docker compose version

Installation

Installation

Signaturmonster is set up via an installer — no manual cloning, no editing of configuration files. The installer checks Docker, asks for your SMTP credentials, downloads all necessary files and starts the containers automatically.

Linux & macOS

Open a terminal and run the following command:

curl -fsSL https://raw.githubusercontent.com/choldermann/signaturmonster/main/install.sh | bash

The installer runs interactively and guides you step by step through the setup. It works on all common Linux distributions as well as macOS. For Proxmox LXC, Raspberry Pi or NAS systems, a simple SSH terminal is sufficient.

Windows

Open PowerShell as Administrator and run the following command:

iex (irm https://raw.githubusercontent.com/choldermann/signaturmonster/main/install.ps1)

What the installer sets up

The installer asks for the following values interactively:

The installer then downloads docker-compose.yml and nginx.conf directly from GitHub, writes the .env file and starts the stack with docker compose pull && docker compose up -d. A random SECRET_KEY is generated automatically.

At the end the installer displays the addresses:

✓ Signaturmonster is running!

  Dashboard:  http://192.168.1.42:8080
  SMTP Port:  192.168.1.42:2587  ← enter this in Thunderbird

Installation

Proxmox LXC Container Setup

Proxmox VE is a popular home server platform on which Signaturmonster runs particularly well. An LXC container is more lightweight than a full VM and shares the kernel of the host — ideal for permanently running services. This guide walks you step by step from container creation to a running Signaturmonster.

Step 1 — Create LXC container

1. Log in to the Proxmox web interface and select the desired node
2. Click Create CT in the top right
3. General: Assign a CT ID (e.g. 200) and a descriptive hostname (e.g. signaturmonster)
4. Template: Choose a recent template — recommended is Debian 12 or Ubuntu 22.04 LTS. Templates can be downloaded in the Proxmox web interface under Datacenter → Storage → CT Templates.
5. Disk: At least 8 GB — 8 GB is easily sufficient for Docker images and Signaturmonster data, 16 GB gives more headroom
6. CPU: At least 1 core, recommended 2 cores
7. Memory: At least 512 MB, recommended 1024 MB (1 GB) — gives the Docker stack comfortable room
8. Network: Select vmbr0 (or your LAN bridge), set DHCP or assign a fixed IP from your subnet. A fixed IP is recommended, since Thunderbird and other clients need a stable address.
9. Click Finish — do not start the container yet

Step 2 — Enable Nesting (for Docker)

Before starting the container, the Nesting option must be enabled. Without it, Docker cannot create its own network namespace.

1. Select the newly created container in the Proxmox web interface
2. Go to Options
3. Double-click on Features
4. Check the Nesting checkbox
5. Optional but recommended: also enable FUSE
6. Click OK

lxc.apparmor.profile: unconfined
features: nesting=1,fuse=1

Step 3 — Start container and install Docker

Start the container and open the console via the Proxmox web interface or SSH.

# Update package list and install dependencies
apt-get update && apt-get install -y ca-certificates curl gnupg

# Add Docker GPG key
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg \
  | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker repository (Debian 12)
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/debian bookworm stable" \
  | tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine and Compose plugin
apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

# Enable and start Docker service
systemctl enable --now docker

# Verify versions
docker --version
docker compose version

# Update package list and install dependencies
apt-get update && apt-get install -y ca-certificates curl gnupg

# Add Docker GPG key
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker repository (Ubuntu 22.04 LTS)
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu jammy stable" \
  | tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine and Compose plugin
apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

# Enable and start Docker service
systemctl enable --now docker

# Verify versions
docker --version
docker compose version

Step 4 — Install Signaturmonster

With Docker running, the Signaturmonster installer can be executed directly inside the container:

curl -fsSL https://raw.githubusercontent.com/choldermann/signaturmonster/main/install.sh | bash

The installer asks interactively for your SMTP credentials and sets everything up. At the end it displays the addresses where you can reach the dashboard and what to enter in Thunderbird. Enter the fixed IP address of the LXC container there (not localhost), so all devices on the network can reach the proxy.

Configuration

Configuration

Create SMTP Accounts

Before Thunderbird or another email client can use the proxy, at least one SMTP account must be created. These credentials are independent of the web UI users and are used exclusively for authentication at the proxy.

1. Open the web UI and navigate to Configuration → SMTP Accounts
2. Click Add Account
3. Enter a username (e.g. the employee's first name or email address) and a password
4. Save — the account is immediately active

You can create as many accounts as you like — e.g. one per employee or one shared account for the whole team.

Set up Thunderbird

Change the outgoing mail server in Thunderbird to the Signaturmonster proxy. You find this setting under Account Settings → Outgoing Server (SMTP).

Create first signature

Open the web UI at http://localhost:8080 and navigate to Signatures → New Signature.

1. Give the signature a name (e.g. "Default Signature")
2. Add blocks via Drag & Drop from the left palette:
   • Text block — free text, name, title, department
   • Image block — logo, profile picture
   • Link block — website, LinkedIn, etc.
   • Social block — pre-built social media icons
   • Divider — horizontal line
   • Banner block — GIF banner (from the banner editor)
3. Configure each block in the right-hand sidebar
4. Use the live preview to see the result
5. Click Save

Using Variables

In text blocks you can use variables that are automatically filled from the sender database when an email is sent. Variables are wrapped in double curly braces:

{{vorname}} {{nachname}}
{{titel}} · {{abteilung}}
{{firma}}

Tel: {{telefon}}
Mobile: {{mobil}}
{{webseite}}

Available variables:

Values are stored per sender in Settings → Senders and automatically substituted when sending.

Create CI Profile

CI profiles define the visual appearance of a brand: primary color, font, logo, background color for the mail body. Via the Mail Beautifier, the incoming mail body is cleaned (foreign signatures removed) and embedded in your CI template.

1. Navigate to Corporate Identity → New CI Profile
2. Upload the company logo (PNG/SVG, max. 2 MB)
3. Choose primary color, accent color and background color
4. Choose the font (Google Fonts are supported)
5. Enable the Mail Beautifier for this profile
6. Save — the profile is now available in the signature rules

Configure Rules

Rules control which signature (and which CI profile) is used for which sender. Without a matching rule, an email is forwarded unchanged.

1. Navigate to Rules → New Rule
2. Enter a sender email address (or a wildcard pattern, e.g. *@example.com)
3. Choose the signature to apply
4. Optional: select a CI profile
5. Optional: enable disclaimer
6. Set priority (lower number = higher priority)
7. Save and activate

Add Disclaimer

Disclaimers are appended to the end of every email. They can be stored as HTML (with formatting) and as a plaintext variant. Signaturmonster automatically inserts the correct variant depending on the mail format.

1. Navigate to Disclaimer → New Disclaimer
2. Enter the HTML text (formatting like <b>, <a> is allowed)
3. Enter the plaintext variant
4. Assign the disclaimer to one or more rules

<!-- HTML disclaimer -->
<p style="font-size:11px;color:#888">
  This email and its attachments are confidential and intended solely
  for the addressee. If you have received this email in error, please
  inform the sender immediately.
  <a href="https://example.com/impressum">Legal Notice</a>
</p>

Banners & Animations

Banners & Animations

Create Banner

The integrated GIF generator creates animated GIF banners directly in the browser, which are embedded as a block in a signature.

1. Navigate to Banners → New Banner
2. Give the banner a name and set the dimensions (recommended: 600×120 px)
3. Add scenes (at least one scene is required)
4. Configure each scene in the scene editor
5. Click Generate preview to render the GIF
6. Save — the banner is now available in the signature designer as a banner block

Scene Editor

Each scene is a frame in the GIF. The scenes play in sequence and can be reordered via Drag & Drop.

Background types

Text animations

Scene settings

• Duration: How long the scene is displayed (in seconds, e.g. 2.0)
• Transition effect: Fade, Cut (hard) or Slide between scenes
• Transition time: Duration of the transition in seconds
• Texts: Multiple text elements per scene, each with its own rich text editor

Outlook Compatibility

Outlook does not support animated GIFs in emails. Signaturmonster solves this automatically with MSO Conditional Comments and CID inline embedding:

<!--[if mso]>
<img src="cid:banner_fallback"
     width="600" height="120"
     alt="Banner">
<![endif]-->

<!--[if !mso]><!-->
<img src="cid:banner_animated"
     width="600" height="120"
     alt="Banner">
<!--<![endif]-->

Both images — the animated GIF and the static PNG fallback from scene 1 — are embedded as CID inline attachments in the email. This means:

• No external URLs — no tracking, no firewall issues
• Images are always displayed, even without an internet connection
• No image loading required when opening the email

Advanced

Advanced

Users & Roles

Signaturmonster supports multiple users with different roles. Users are managed in the web UI under Settings → Users.

Roles

SMTP users

Each sender (SMTP user) has their own entry under Settings → Senders. Profile data (for variables) and SMTP credentials for the real mail server are stored there.

Updates

The updater service regularly checks the GitHub Container Registry (ghcr.io/choldermann) for new image versions. When new versions are found, a notification appears in the web UI.

Manual update

# Pull new images
docker compose pull

# Restart stack with new images
docker compose up -d

# Clean up old (unused) images
docker image prune -f

Automatic update

The built-in updater service can be configured to automatically apply updates. This is controlled via an environment variable:

# Enable automatic updates (true/false)
AUTO_UPDATE=true

# Check interval in minutes (default: 60)
UPDATE_INTERVAL=60

Security & Cryptography

S/MIME and PGP — Architectural clarification

Signaturmonster is an SMTP proxy that modifies email content (signature, branding, disclaimer). This is structurally incompatible with end-to-end encryption (S/MIME, PGP), whose core claim is: "I, the sender, signed exactly this content."

A proxy that modifies content and then signs it cryptographically could not make that claim — it already changed the content. This is not a bug, but a fundamental conflict that all content-modifying mail systems share — including commercial cloud providers like Exclaimer or CodeTwo.

Workaround for mandatory E2E signing

If you require personal end-to-end signing (e.g. law firms, authorities with QES requirements under eIDAS):

1. Set the cryptographic signature in your email client before the email is sent to the proxy
2. Disable all proxy functions for that email using #sm:off

The #sm:off command is written on its own line in the email body — the proxy then forwards the email unmodified. The command itself is removed before delivery.

Mail Queue & Storage

Incoming emails are received by the SMTP proxy and first stored in a local SQLite queue on your server before processing and forwarding begins. The emails remain entirely within your infrastructure — there is no connection to external services for email delivery at any point.

Queue overview in the web UI

Under System → Mail Queue, all entries are visible with status, sender, recipient and subject:

Downloading emails

Individual emails can be downloaded directly from the queue overview — useful for debugging, audit purposes or reviewing failed delivery attempts. Failed entries can also be manually re-queued.

Retry strategy

On delivery failure, the proxy automatically retries with exponential backoff:

Troubleshooting

Here are the most common problems and their solutions:

SMTP connection fails

Check the logs of the SMTP proxy container:

docker compose logs smtp-proxy

Common causes:

• Port 587 is already in use on the host — change PROXY_PORT in .env
• SMTP_HOST or SMTP_PORT incorrectly configured
• Firewall blocking the outgoing port

Web UI not reachable

# Check status of all containers
docker compose ps

# Show nginx logs
docker compose logs nginx

# Show backend logs
docker compose logs backend

• Make sure port 8080 (or your configured port) is not blocked
• The frontend container needs a moment to start on first run

Signature is not injected

• Check that a rule for the sender exists and is active
• Make sure the email was sent via the Signaturmonster proxy (port 587)
• Check the logs: docker compose logs smtp-proxy

GIF banner not displayed in Outlook

• This is expected behavior — Outlook shows the static PNG fallback
• Check that Scene 1 is correct and visually meaningful
• Make sure the banner is embedded as CID (default behavior)

Database reset

# Warning: deletes all data!
docker compose down
rm -rf ./data
docker compose up -d