modmail: A Python repository from JamieIsGeek

A feature-rich Modmail bot for Discord.

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.

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 (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.

Installation

Q: Where can I find the Modmail bot invite link?

A: 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).

There are a few options for hosting your very own dedicated Modmail bot.

Patreon hosting
Local hosting (VPS, Dedicated Server, RPi, your computer, etc.)
PaaS (we provide a guide for Heroku)

Patreon Hosting

If you don't want the trouble of renting and configuring your server to host Modmail, we got a solution for you! We offer hosting and maintenance of your own, private Modmail bot (including a Logviewer) through Patreon. Join our Modmail Discord Server for more info!

Local hosting (General Guide)

Modmail can be hosted on any modern hardware, including your PC. For stability and reliability, we suggest purchasing a cloud server (VPS) for under $10/mo. If you need recommendations on choosing a VPS, join our Discord server, and we'll send you a list of non-affiliated hosting providers. Alternatively, we can host Modmail for you when you're subscribed to our Patreon.

This guide assumes you've downloaded Python 3.10 and added python and pip to PATH.

Clone this repo

$ git clone https://github.com/modmail-dev/modmail
$ cd modmail

Create a Discord bot account, grant the necessary intents, and invite the bot (guide)
Create a free MongoDB database (guide, follow it carefully!)
Rename the file .env.example to .env and fill it with appropriate values
- If you can't find .env.example because it's hidden, create a new text file named .env, then copy the contents of this file and replace the placeholders with their values
- If you're on Windows and cannot save the file as .env, save it as .env. instead (this only applies to Windows!)
- If you do not have a Logviewer yet, leave the LOG_URL field as-is
Update pip, install pipenv, and install dependencies using pipenv
```
$ pip install -U pip
$ pip install pipenv
$ pipenv install
```
Start the bot
```
$ pipenv run bot
```
Set up the Logviewer, see the Logviewer installation guide

Local Hosting (Docker)

We provide support for Docker to simplify the deployment of Modmail and Logviewer. We assume you already have Docker and Docker Compose Plugin installed, if not, see here.

Create a Discord bot account, grant the necessary intents, and invite the bot (guide)
Create a file named .env, then copy the contents of this file and replace the placeholders with their values
Create a file named docker-compose.yml, then copy the contents of this file, do not change anything!
Start the bot
```
$ docker compose up -d
```
- For older Docker versions, you may need to run docker-compose up -d instead
View the status of your bot, using docker ps and docker logs [container-id]

Our Docker images are hosted on GitHub Container Registry, you can build your own image if you wish:

$ docker build --tag=modmail:master .

Then simply remove ghcr.io/modmail-dev/ from the docker-compose.yml file.

Local Hosting (OS-Specific)

This guide is a WIP. Join our Discord server for more info.

Platform as a Service (PaaS)

You can host this bot on Heroku (no longer free).

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.

When using Heroku, you can 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.

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 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 are available in our Modmail Support Server.

Contributing

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!

Beta Testing

Our development branch is where most of our features are tested before public release. Be warned that there could be bugs in various commands so keep it away from any large servers you manage.

If you wish to test the new features and play around with them, feel free to join our Public Test Server. Bugs can be raised within that server or in our Github issues (state that you are using the development branch though).

JamieIsGeek/modmail