Skip to content
A feature rich discord Modmail bot
Python Dockerfile
Branch: master
Clone or download

Latest commit

Taaku18 Merge pull request #2784 from DiscordFederation/master
Ensure optional dependencies in pyproject.toml can be installed by poetry.
Latest commit adaef04 Apr 16, 2020


Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update Jan 9, 2020
cogs support newer venv and virtualenv Mar 12, 2020
core v3.4.1, mask errors Dec 18, 2019
plugins Added title in githubstats plugin Mar 10, 2020
.bandit_baseline.json Update travis Oct 7, 2019
.dockerignore Fixed typos Nov 28, 2019
.env.example Update and rename config.json.example to .env.example Jun 16, 2019
.gitignore v3.3.2, fix perm bug Dec 9, 2019 Delete notes, "?logs delete", linked alias (#402) Nov 2, 2019
.pylintrc Reformat code Nov 16, 2019 Spell check Jan 9, 2020 Create May 21, 2019 Spell check Jan 9, 2020
Dockerfile Improved dockerfile and changed stale limit Nov 17, 2019
LICENSE Update LICENSE Nov 2, 2019
Pipfile officially v3.4.0 Dec 14, 2019
Pipfile.lock officially v3.4.0 Dec 14, 2019
Procfile Updated pipfile Jul 12, 2019 Update Mar 13, 2020
SPONSORS.json Update SPONSOR.json (#404) Oct 31, 2019
app.json Removed "update" Aug 12, 2019 v3.4.1, mask errors Dec 18, 2019
poetry.lock Ensure optional dependencies in pyproject.toml can be installed by po… Apr 16, 2020
pyproject.toml Ensure optional dependencies in pyproject.toml can be installed by po… Apr 16, 2020
requirements.min.txt 3.3.2-dev3 fallback category Nov 26, 2019
runtime.txt Bump to Python 3.7.6 Jan 6, 2020

A feature-rich Modmail bot for Discord.

Bot instances Support Python 3.7 Made with Python 3.7 MIT License

What is Modmail?

Modmail is similar to Reddit's Modmail, both in functionality and purpose. It serves as a shared inbox for server staff to communicate with their users in a seamless way.

This bot is free for everyone and always will be. If you like this project and would like to show your appreciation, you can support us on Patreon, cool benefits included!

How does it work?

When a member sends a direct message to the bot, Modmail will create a channel or "thread" into a designated category. All further DM messages will automatically relay to that channel; any available staff can respond within the channel.

Our Logviewer will save the threads so you can view previous threads through their corresponding log link. Here is an example.


  • 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 (premium Patreon 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.


Where can I find the Modmail bot invite link?

Unfortunately, due to how this bot functions, it cannot be invited. The lack of an invite link is to ensure an individuality to your server and grant you full control over your bot and data. Nonetheless, you can quickly obtain a free copy of Modmail for your server by following one of the methods listed below (roughly takes 15 minutes of your time).


You can host this bot on Heroku.

Installation via Heroku is possible with your web browser alone. The installation guide (which includes a video tutorial!) will guide you through the entire installation process. If you run into any problems, join our Modmail Discord Server for help and support.

To configure automatic updates:

  • Login to GitHub and verify your account.
  • Fork the repo.
  • Install the Pull app for your fork.
  • Then go to the Deploy tab in your Heroku account of your bot app, select GitHub and connect your fork (usually by typing "Modmail").
  • Turn on auto-deploy for the master branch.

Hosting for Patreons

If you don't want to go through the trouble of setting up your very own Modmail bot or wish to support this project, we got a solution for you! We offer the complete installation, hosting, and maintenance of your Modmail with Patreon. Join our Modmail Discord Server for more info!


Local hosting of Modmail is also possible. First, you will need Python 3.7.

Follow the installation guide and disregard deploying the Heroku bot application. If you run into any problems, join our Modmail Discord Server for help and support.

Clone the repo:

$ git clone
$ cd modmail

Install dependencies:

$ pipenv install

Rename the .env.example to .env and fill out the fields. If .env.example is nonexistent (hidden), create a text file named .env and copy the contents of .env.example then modify the values.

Finally, start Modmail.

$ pipenv run bot


This repo supplies a Dockerfile for simplified deployment.

You can build your own Docker image:

$ docker build . --tag=modmail

Or run directly from a pre-built version from

  • Kyber's:
$ docker pull kyb3rr/modmail

And to run your docker image:

$ docker run --env-file .env kyb3rr/modmail
  • .env should be the path to your env file; you can also supply a path: /path/to/.env.


Special thanks to our sponsors for supporting the project.

Become a sponsor on Patreon.


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 or visit the Unofficial List of Plugins for a list of plugins contributed by the community.

To develop your own, check out the plugins documentation.

Plugins requests and support is available in our Modmail Plugins Server.


Contributions to Modmail are always welcome, whether it be improvements to the documentation or new functionality, please feel free to make the change. Check out our contributing guidelines before you get started.

If you like this project and would like to show your appreciation, support us on Patreon!

You can’t perform that action at this time.