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

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.

• Robust implementation:

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

This list is ever-growing thanks to active development and our exceptional contributors. See a full list of documented commands by using the ?help command.

Installation

This is a general installation guide. Refer to the documentation for detailed user guide.

This guide assumes you have git, and a supported Python version installed and added to system PATH.

1. Clone the repository

   $ git clone https://github.com/raidensakura/modmail
   $ cd modmail

2. Create a Discord bot account, grant the necessary intents, and invite the bot.
3. Create a free MongoDB database.
4. Rename the file .env.example to .env and fill it with appropriate values
5. Update pip, install pipenv, and install dependencies using pipenv

   $ pip install -U pip
   $ pip install pipenv
   $ pipenv install

6. Start the bot

   $ pipenv run bot

7. Load the logviewer plugin included with Modmail with ?plugin load @local/logviewer

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/raidensakura/modmail:stable

• Running with Docker Compose:

  $ docker compose up -d

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 of the scope of the core functionality of Modmail.

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.

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.

Support for this forked version of Modmail can be requested through Raiden's Discord server. As I don't have a dedicated team to answer questions and provide help, it will be be answered when I'm available.

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 pipenv

   $ pipenv install --dev

2. Install the pre-commit hook

   $ pre-commit install

Alternatively, you can also lint the codebase manually

$ black .
$ ruff .