Fork² of a feature-rich Modmail bot for Discord written in Python.

Note

This is a hard fork of modmail by khakers based on raidensakura's fork of modmail. This fork is not affiliated with the original modmail project.

It was done to add features that were not being added to the original modmail project due slow PR merges and to better align with what I wanted for modmail-viewer (and now modmail-view-ts). You probably shouldn't use this, but if you for some reason do, it does have some extra features, fixes, and bugs. I try to fix issues that I've caused as quickly as is reasonable, but my time is very limited.

I am the developer of modmail-viewer and modmail-viewer-ts, which are the recommended way to view logs for this fork.

Features

• Highly Customisable:

  • Bot activity, prefix, category, log channel, etc.
  • Command permission system.
  • Interface elements (color, responses, reactions, etc.).
  • Snippets and command aliases.
  • Minimum duration for accounts to be created before allowed to contact Modmail (account_age).
  • Minimum length for members to be in the guild before allowed to contact Modmail (guild_age).

• Advanced Logging Functionality:

  • When you close a thread, Modmail will generate a log link and post it to your log channel.
  • Native Discord dark-mode feel.
  • Markdown/formatting support.
  • Login via Discord to protect your logs (optional feature).
  • See past logs of a user with ?logs.
  • Searchable by text queries using ?logs search.
  • S3 Attachment Archival: Archive message attachments to durable S3 storage to preserve access beyond Discord's URL expiration (~7 days). Supports AWS S3 and S3-compatible services.

• Robust implementation:

  • Schedule tasks in human time, e.g. ?close in 2 hours silently.
  • Editing and deleting messages are synced.
  • Support for a diverse range of message contents (multiple images, files).
  • Paginated commands interfaces via reactions.

Installation

Running the Docker Image

This guide assume you already have Docker or Docker Compose installed.

• Running with docker:

  $ docker run --env-file=.env --name=modmail ghcr.io/khakers/openmodmail:latest

• Running with Docker Compose:

  $ docker compose up -d

Note

You should always view the docker compose file to understand the services that it runs and modify it to your wishes.

I always recommend using a specific tagged release or commit as your image ( i.e. ghcr.io/khakers/openmodmail:sha-32asfd7 or an immutable sha256 hash)

Docker image tags

To pin to a specific version, use either the sha256 hash of the image or the commit sha. ex: ghcr.io/khakers/openmodmail:sha-24286a. For most users, the latest tag is recommended and will be updated to point to stable releases when they become available.

Warning

The latest tag currently points to development releases, but will change in the future.

Image tag variants

Images with '-supportutils' include a fixed version of the supportutils package, used by a number of plugins. Images with '-pip' include pip installed into the virtual environment, which is required for some plugins. It is not currently included by default

Plugins

Modmail supports the use of third-party plugins to extend or add functionalities to the bot. Plugins allow niche features as well as anything else outside the scope of core Modmail functionality.

You can find a list of third-party plugins using the ?plugins registry command on the bot or by reading through the official REGISTRY.json.

Note

Modmail has deleted their github wiki

To develop your own, check out the plugins documentation.

Plugins requests and support are available in the Modmail Support Server.

Support & Issues

Issues with the bot can be opened through GitHub Issues.

Contributing

Check out the contributing guidelines before you get started.

The develop branch is where most of the features are tested before stable release.

This project has included pre-commit script that automatically runs black and ruff linter on every commit.

1. Install development dependencies inside pdm

   $ pdm sync -d

2. Install the pre-commit hook

   $ pdm install --plugins

   The pre-commit hook should be automatically installed

Alternatively, you can also lint the codebase manually

$ black .
$ ruff .