imap-spam-cleaner

README

IMAP spam cleaner

A tool to clean up spam in your imap inbox.

Check the Wiki for detailed information.

How does it work

This application loads mails from configured imap inboxes and checks their contents using the defined provider. Depending on a spam score, the message can be moved to the spam folder, keeping your inbox clean.

Example

$ docker run -v ./config.yml:/app/config.yml dominicgisler/imap-spam-cleaner:latest
INFO   [2026-02-28T16:53:41Z] Starting imap-spam-cleaner v0.5.3
DEBUG  [2026-02-28T16:53:41Z] Loaded config
INFO   [2026-02-28T16:53:41Z] Scheduling inbox info@example.com (*/5 * * * *)
INFO   [2026-02-28T16:55:00Z] Handling info@example.com
DEBUG  [2026-02-28T16:55:00Z] Available mailboxes:
DEBUG  [2026-02-28T16:55:00Z]   - INBOX
DEBUG  [2026-02-28T16:55:00Z]   - INBOX.Drafts
DEBUG  [2026-02-28T16:55:00Z]   - INBOX.Sent
DEBUG  [2026-02-28T16:55:00Z]   - INBOX.Trash
DEBUG  [2026-02-28T16:55:00Z]   - INBOX.Spam
DEBUG  [2026-02-28T16:55:00Z]   - INBOX.Spam.Cleaner
DEBUG  [2026-02-28T16:55:00Z] Found 34 messages in inbox
DEBUG  [2026-02-28T16:55:00Z] Found 5 UIDs in timerange
INFO   [2026-02-28T16:55:00Z] Loaded 5 messages
DEBUG  [2026-02-28T16:55:06Z] Spam score of message #478 (Herzlichen Glückwunsch! Ihr Decathlon-Geschenk wartet auf Sie. 🎁): 90/100
DEBUG  [2026-02-28T16:55:12Z] Spam score of message #479 (Leider ist bei der Verarbeitung Ihrer Zahlung ein Problem aufgetreten.): 90/100
DEBUG  [2026-02-28T16:55:18Z] Spam score of message #480 (Das neue Geheimnis gegen Bauchfett!): 92/100
DEBUG  [2026-02-28T16:55:26Z] Spam score of message #481 (Schnell: 1 Million / Lady Million): 80/100
DEBUG  [2026-02-28T16:55:32Z] Spam score of message #483 (Vermögen x4 zu Fest): 85/100
INFO   [2026-02-28T16:55:32Z] Moved 4 messages

How to use

Using image from docker hub (recommended)

• Create config.yml matching your inboxes (example below)
• Create docker-compose.yml if using docker compose (example below)
• Start the container with: docker compose up -d
• Or with: docker run -d --name imap-spam-cleaner -v ./config.yml:/app/config.yml dominicgisler/imap-spam-cleaner

From source with local Go installation

• Clone this repository
• Install Go version 1.26+
• Load dependencies (go get ./...)
• Create config.yml matching your inboxes (example below)
• Run the application (go run .)

From source with docker

• Clone this repository
• Install docker
• Build the docker image: docker build -f Dockerfile -t dominicgisler/imap-spam-cleaner .
• Create config.yml matching your inboxes (example below)
• Create docker-compose.yml if using docker compose (example below)
• Start the container with: docker compose up -d
• Or with: docker run -d --name imap-spam-cleaner -v ./config.yml:/app/config.yml dominicgisler/imap-spam-cleaner

Sample docker-compose.yml

services:
  imap-spam-cleaner:
    image: dominicgisler/imap-spam-cleaner:latest
    container_name: imap-spam-cleaner
    hostname: imap-spam-cleaner
    restart: always
    volumes:
      - ./config.yml:/app/config.yml:ro

Configuration

Use this configuration as an example for your own setup. Save the file as config.yml on your disk (where the application will run) or mount the correct path into the docker container.

logging:
  level: debug                    # logging level (panic, fatal, error, warn, info, debug, trace)

providers:                        # providers to be used for inboxes
  prov1:                          # provider name
    type: openai                  # provider type
    config:                       # provider specific configuration
      apikey: some-api-key        # openai apikey
      model: gpt-4o-mini          # openai model to use
      maxsize: 100000             # message size limit for prompt (bytes)
      prompt: |                   # prompt to be sent to the model
        Analyze the following email for its spam potential.
        Return a spam score between 0 and 100. Only answer with the number itself.

        From: {{.From}}
        To: {{.To}}
        Delivered-To: {{.DeliveredTo}}
        Cc: {{.Cc}}
        Bcc: {{.Bcc}}
        Subject: {{.Subject}}

        Content:
        {{.Content}}
  prov2:                          # provider name
    type: ollama                  # provider type
    config:                       # provider specific configuration
      url: http://127.0.0.1:11434 # ollama url
      model: gpt-oss:20b          # ollama model to use
      maxsize: 100000             # message size limit for prompt (bytes)
  prov3:                          # provider name
    type: spamassassin            # provider type
    config:                       # provider specific configuration
      host: 127.0.0.1             # spamassassin host
      port: 783                   # spamassassin port
      maxsize: 300000             # message size limit
      timeout: 10s                # connection timeout

whitelists:                       # trusted senders as regexp, not to be analyzed
  whitelist1:                     # example with exact addresses
    - ^.* <info@example.com>$     # matches <info@example.com>
    - ^.* <contact@domain.com>$   # matches <contact@domain.com>
  whitelist2:                     # example with only domain match
    - ^.* <.*@example.com>$       # matches for all @example.com addresses
    - ^.* <.*@domain.com>$        # matches for all @domain.com addresses

inboxes:                          # inboxes to be checked
  - schedule: "* * * * *"         # schedule in cron format (when to execute spam analysis)
    host: mail.domain.tld         # imap host
    port: 143                     # imap port
    tls: false                    # imap tls
    username: user@domain.tld     # imap user
    password: mypass              # imap password
    provider: prov1               # provider used for spam analysis
    inbox: INBOX                  # inbox folder
    spam: INBOX.Spam              # spam folder
    minscore: 75                  # min score to detect spam (0-100)
    minage: 0h                    # min age of message
    maxage: 24h                   # max age of message
    whitelist: whitelist1         # whitelist to use, empty/missing = no whitelist

Contributors

Dominic Gisler

Niklas Steiner