# Introduction
https\://github.com/modmail-dev/modmail
Modmail is a self-hosted Discord bot for your server. It works similar to [Reddit](https://reddit.zendesk.com/hc/en-us/articles/210896606-What-is-Modmail-)'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 [**BuyMeACoffee**](https://buymeacoffee.com/modmaildev/membership), cool benefits included!
## What is Modmail used for?
When a member sends a direct message to Modmail, the bot will create a channel (we call it a "thread") into a designated category. All further DM messages will automatically relay to that channel, then any available staff can respond within the channel. Compared to ticketing bots, Modmail allows easier and more organised discussions among staff.
An example of a Modmail thread.
Our Logviewer will save the threads so your staff can view previous threads through their corresponding log link. ~~Here is an~~ [~~**example**~~](https://publicmodmail.logs.vodka/logs/example).
## Features
#### **Highly customisable**
* Changeable bot status, prefix, category, log channel, etc.
* Versatile command permission system.
* Interface elements (color, responses, reactions, etc.).
* Snippets and command aliases.
* Minimum durations for account age and time in server before allowed to contact Modmail.
* Plugin support for extending functionality.
* Custom thread creation messages and thread naming formats.
* Configurable auto-close, inactivity, and notification settings.
**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.
* Discord authentication-protected logs ([Patreon/BMAC-only feature](https://buymeacoffee.com/modmaildev/membership)).
* See past logs of a user with `?logs`.
* Searchable by text queries using `?logs search`.
#### **Robust implementation**
* Ease of installation: you can get your Modmail bot running in under 10 minutes!
* Schedule tasks in human time, e.g. `?close in 2 hours silently`.
* Editing and deleting messages are synced.
* Support for images, files, stickers, and other attachments.
* Internal notes and moderator-only discussions.
* Paginated commands interfaces via buttons.
* Multi-user conversations and private thread management tools.
This list is ever-growing thanks to active development by our exceptional contributors. See a full list of available commands by using the `?help` command.
## Installation
Visit our [installation page](/installation) for detailed instructions on setting up Modmail for your server.
## Supporting the project
You have various options to help the project. Giving this repository a star is greatly appreciated. You can also help people that have trouble setting up Modmail at our [Discord server](https://discord.gg/cnUpwrnpYb).
## Contributing
Support Modmail with your contributions! Whether it be improvements to the documentation or new functionality, please feel free to make the change. Check out our [contributing guidelines](https://github.com/modmail-dev/modmail/blob/master/.github/CONTRIBUTING.md) before you get started.
## Next Steps
* Read about [installing Modmail](/installation).
* Become familiar with [Modmail commands and functionalities](https://github.com/kyb3rr/modmail-docs/tree/main/getting-started.md).
{% hint style="info" %}
Throughout this documentation when we're referring to bot commands, we will assume the prefix of the bot to be ? and will display them like in this example: ?help.\
\
**Optional** arguments will be enclosed in square brackets:\
Example: ?close \[time] \[reason] \[silently]\
\
**Required** arguments will be enclosed in angle brackets:\
Example: ?contact \
{% endhint %}
# Choosing a Host
This page briefly describes our recommendations for choosing a host.
Choosing where to host your Modmail bot is one of the most important decisions you’ll make during setup. A good host can make your Modmail bot invaluable for running your server, a bad host can make it useless.
There are three main factors to balance when selecting a host:
1. **Cost**
2. **Availability (Uptime)**
3. **Simplicity**
{% hint style="info" %}
If you’re looking for specific providers that have been tested by our community, check the [Recommended Hosts](/choose-host/recommended-hosts) page.\
You can also view hosts that are **not suitable** for Modmail on the [Unrecommended Hosts](/choose-host/unrecommended-hosts) page.
{% endhint %}
***
## Understanding the Tradeoffs
No hosting option is perfect — choosing where to host your bot always means balancing cost, uptime, and simplicity.
You may have heard the saying *“cheap, good, fast — pick two.”* Hosting Modmail (or any Discord bot) follows a similar idea. In our case, the three factors are **Cost**, **Uptime**, and **Simplicity**. You can usually get two of them, but you’ll have to compromise on the third. Here’s a quick overview:
| Low Cost | High Uptime | Simple | Example |
| -------- | ----------- | ------ | ---------------------- |
| ✅ | ❌ | ✅ | Free Pterodactyl Panel |
| ✅ | ✅ | ❌ | Private VPS |
| ❌ | ✅ | ✅ | Heroku |
{% hint style="warning" %}
**Free Hosting Platforms are Discouraged**
Over the years, the Modmail team has spent many hours researching and recommending free hosting platforms. Starting in 2025, we are no longer spending the time, or recommending platforms purley for being free.
Free platforms usually have, or develop one of these problems: remove free tier, high downtime, problematic server connection, or terminating instances without notice.
{% endhint %}
### "Minimum Spec"
The Modmail project does not have a minimum specification required to use run your bot. However, generally, if you hear anyone from our team, or read on this page the term **minimum spec**, we are referring to this:
| System Spec | Minimum Value |
| ------------- | ------------------------------- |
| CPU | 1 core, speed mostly irrelevant |
| RAM | 1GB |
| Storage | \~2GB (on top of OS) |
| Network Speed | > 10 Mbps |
***
## Hosting Decision Flow
{% stepper %}
{% step %}
### Step 1 — Identify Your Needs
Modmail is a very lightweight bot, very minimal resources are required.
> Do you have more than 1000 members in your server?
**If not:** you likely do not need more than 512mb of memory and 1 CPU core.
**If yes:** you can potentially get away with the minimum spec, but you should consider upgrading.
> Do you require your Modmail bot to be online with 0 downtime?
**If yes:** you want to steer away from free hosts, and in most cases, local hosting as well. *Clarification: for our team, "local hosting" is hosting on a computer that you have in your house, not a VPS in a datacenter*
> Do you plan to have significant usage of your bot?
**If yes (ie many plugins, hundreds of active threads at once - being replied to not sitting dormant, etc):** you can potineitally get away with the minimum spec, but you should consider upgrading.
**If you aren't sure:** Talk with our [community and team](https://discord.gg/nfErcs7mDM).
**If no:** use the minimum spec above.
> How technical are you?
If you struggle with technology, you may want to consider a PaaS (Platform as a Service) host, which handles the backend of a server for you. If you have strong technical proficiencies (or a willingness to research and learn), a VPS or local hosting is likely a better fit for you.
{% endstep %}
{% step %}
### Step 2 — Decide on Your Budget
* **$0:** Not recommended. Free hosts are unstable and may terminate at any time.
* **$2–10/month:** Ideal for most users. Reliable cloud or VPS hosting with full control.
* **$15+/month:** Used for hosting multiple **large** modmail bots and/or extra services besides modmail. Unnecessary for hosting a single modmail bot.
{% endstep %}
{% step %}
### Step 3 — Pick Your Platform Type
| Platform Type | Best For | Pros | Cons | Examples |
| -------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------- | --------------------------- | ------------------------------------------------------- |
| **PaaS** | Simple setup requiring less technical knowledge | Simple UI, auto-deploys, managed | Paid Plan usually Required | Heroku, Railway |
| **Hetzner / OVH / DigitalOcean (VPS)** | Users with basic technical knowledge | Full control, high uptime | Linux/Docker setup required | See [Recommended Hosts](/choose-host/recommended-hosts) |
| **Local Hosting** | Users with special cost requirements, or other locally running, always on, computer at home. | No subscription, complete control | Local outages affect uptime | Old Computer, Raspberry Pi, etc |
| {% endstep %} | | | | |
| {% endstepper %} | | | | |
## Related Pages
* [Recommended Hosts](/choose-host/recommended-hosts) — Tested VPS and PaaS providers our users trust.
* [Unrecommended Hosts](/choose-host/unrecommended-hosts) — Platforms known to cause Modmail reliability issues.
{% hint style="success" %}
### Our Recommendation for Most Users
For nearly all cases, we recommend a cheap Virtual Private Server from one of our [Recommended Hosts](/choose-host/recommended-hosts).
For users who do not wish to pay, we recommend locally hosting the bot from hardware you already own, like a Raspberry Pi, or old computer you can keep running 24/7 in your house.
In situations where you significantly struggle with technology, a PaaS option *may* be better with you. Feel free to consult with our [team](https://discord.gg/nfErcs7mDM) if you don't know if this is the best option for you.
If you want the simplest possible method of getting your bot online, we would recommend one of our two native Modmail hosts, [buymeacoffee.com/modmaildev](https://buymeacoffee.com/modmaildev) or [modmail.lvl.lol](https://modmail.lvh.lol). Both run a panel that is purpose built and custom developed solely for the purpose of running Modmail.
{% endhint %}
{% hint style="danger" %}
## A Caution on Free Pterodactyl based hosts.
Many hosting "companies" have popped up in recent years using the free, open source, [Pterodactyl](https://pterodactyl.io/) hosting platform. These hosting sites are particularly problematic. With the biggest concern usually revolving around **your data security**. Many, if not all, of these platforms do not provide, possess, or follow proper agreements relating to the access of your uploaded information. This includes your MongoDB Conncection URI, and Bot Token, allowing the "staff" of these "companies" to access any message ever sent to or from your bot, any message in your server, and carry out actions as your bot (ie. deleting channels, reading messages, banning users).
Additionally, many of these hosts are run with substandard hardware and infrastucture, usually resulting to temporary IP bans from Discord, poor uptime, poor performance, improper dependancy installation, and more.
We **strongly** encourage you to conduct **full and complete** research before using these hosts. *Our general recommendation is to: **avoid them.***
{% endhint %}
# Recommended Hosts
These hosts are hosts we, and members of our community have had success with.
{% hint style="info" %}
The Modmail Team does not have any affiliation with any hosting providers or platforms.
{% endhint %}
## Official Modmail Hosting
The Modmail team provides official hosting of the bot using Buy Me a Coffee. Monthly plans start at $4/month.
Most plans also include premium logviewer, which allows locking a Loglink using OAuth Discord Login, and a dashboard.
Official Hosting is run on redundant servers with automatic failover.
See details on [Buy Me a Coffee](https://buymeacoffee.com/modmaildev/membership).
## VPS Providers
### ✦ Large Providers:
[Hetzner](https://www.hetzner.com/cloud) (DE†) ↦ Cloud - CAX11 for $4.10/mo. †US region also available for an extra 61¢ (CPX11).
[OVHCloud](https://www.ovhcloud.com/en/vps) (CA) ↦ VPS - Starter for $4.20/mo.
### ✦ Lesser-Known Providers:
[GalaxyGate](https://galaxygate.net/hosting/vps) (US) ↦ VPS - Standard 2GB for $5.00/mo.
[Netcup.eu](https://www.netcup.eu/vserver/vps.php) (DE) ↦ vServer - VPS 200 G10s for $3.52/mo. (6 mo. contract).
[HostHatch](https://hosthatch.com/products) (US) ↦ Compute VMs - NVMe 2 GB for $4.00/mo.
### ✦ Other Reliable Providers:
[BuyVM](https://buyvm.net/kvm-dedicated-server-slices)
[Digital Ocean](https://www.digitalocean.com/products/droplets)
[Linode](https://www.linode.com/products/shared)
[Tier.net](https://www.tier.net/vps)
[Vultr](https://www.vultr.com/products/cloud-compute)
[IONOS](https://www.ionos.ca/servers/vps)
### ✦ Budget Providers: Cheap! But Less Reliable.
[HostVDS](https://hostvds.com/#cloud) (US) ↦ Cloud VDS - 1 vCPU 2 GB for $1.99/mo.
[RackNerd](https://www.racknerd.com/NewYear/) (US) ↦ Intel KVM VPS - 2 GB KVM VPS for $17.38/yr.
{% hint style="info" %}
Pricing current as of time of publication, October 5th, 2024. Check websites for up to date pricing information
{% endhint %}
{% hint style="warning" %}
Be sure to research hosting providers before renting a server from one. Our recommendations and experiences should be used as recommendations only, we cannot guarantee any specific experience with any provider, nor can we provide billing or other support regarding the operating system, or availability of servers. Support is only provided through the process of installing and maintaining Modmail itself.
{% endhint %}
{% hint style="info" %}
The Modmail Team always recommends exercising security best practices with any server. While we are unable to provide official support on this matter, we can recommend some good places to start:
* [Digital Ocean](https://www.digitalocean.com/community/tutorials/an-introduction-to-securing-your-linux-vps)
* [Plesk Recommendations](https://www.plesk.com/blog/various/how-to-secure-your-linux-server-a-detailed-guide/#)
* [ninjaOne Recommendations](https://www.ninjaone.com/blog/key-steps-for-a-more-secure-linux-server/)
* [Linux.org Fourms Recommendations](https://www.linux.org/threads/the-ultimate-guide-to-reasonable-security-for-your-debian-ubuntu-linux-server-for-new-linux-admins.49199/)
*Consider these a starting point, but be sure to do your own research. The Modmail Team holds no liability for any security mishaps that may occur with a server not rented by us and under our full, direct, and exclusive control. (in other words: we aren't responsible for your server)*
{% endhint %}
## PaaS Providers
PaaS Hosting is usually more expensive, but a simpler to setup solution, which removes the need for securing a server, SSH configurations, terminal usage, and similar. However, because of this the platforms are usually more restricted, and difficult to troubleshoot. Despite this they are still an adequate and supported option.
[Heroku](https://www.heroku.com/)
[Railway](https://railway.com/)
{% hint style="danger" %}
## A Caution on Free Pterodactyl based hosts.
Many hosting "companies" have popped up in recent years using the free, open source, [Pterodactyl](https://pterodactyl.io/) hosting platform. These hosting sites are particularly problematic. With the biggest concern usually revolving around **your data security**. Many, if not all, of these platforms do not provide, possess, or follow proper agreements relating to the access of your uploaded information. This includes your MongoDB Conncection URI, and Bot Token, allowing the "staff" of these "companies" to access any message ever sent to or from your bot, any message in your server, and carry out actions as your bot (ie. deleting channels, reading messages, banning users).
Additionally, many of these hosts are run with substandard hardware and infrastucture, usually resulting to temporary IP bans from Discord, poor uptime, poor performance, improper dependancy installation, and more.
We **strongly** encourage you to conduct **full and complete** research before using these hosts. *Our general recommendation is to: **avoid them.***
{% endhint %}
# Unrecommended Hosts
These hosts are hosts we, and members of our community have had little success with.
{% hint style="warning" %}
The Modmail team does not in any way intend to defame, harm, or otherwise create badwill between Modmail and the open source community as a whole, and any hosting provider. We simply provide this list to our users through our experience. We do not in any way imply that these hosts are bad, unreliable, or that it is not possible to use them, we simply state that these are not a good fit for hosting Modmail.
{% endhint %}
### Repl.it
* [Website](https://repl.it)
* Repl.it is a provider aimed at hosting websites. Meaning, it does not have the proper tools and features to properly host the Modmail bot.
* This host is particularly problematic, and there have been many documented unexplainable issues that occur when hosting your bot with this method. Because of this it is **strongly discouraged** for use.
### Bot-hosting.net
* [Website](https://bot-hosting.net/)
* bot-hosting.net is a free or low cost hosting provider that bases their hosting platform on the common free and open-source panel [Pterodactyl](https://pterodactyl.io/).
* Hosting on any Pterodactyl panel based host is already challenging, however, bot-hosting.net shares IP addressess among users, which has resulted in high numbers of our users reporting rate limits being applied to their bot. In other words: your bot will randomly stop working with nothing you can do to fix it.
### Wispbyte
* [Website](https://wispbyte.com/)
* Similar setup and issues as Bot-Hosting.net — shared resources and inconsistent reliability.
* Wispbyte's support team has also been seen to suggest random breaking changes to attempt to make the bot run. They do not work.
### Karlo Hosting
* [Website](https://karlo-hosting.com/)
* Another free or low cost hosting provider based on the Pterodactyl panel, our users have reported unusual difficulties deploying Modmail with this host due to their specific Pterodactyl configuration and limitations.
### Discord Bot Hosting
* [Website](https://discordbothosting.com/)
* Pterodactyl based host that can have issues with ratelimits due to shared IP addresses and reasons that have been listed above.
### Kairo Hositing
* Discord Only
* Kairo Hosting is a discord server based hosting provider that provides free hosting for Modmail bots. However, the Modmail team was provided evidence that the host expressed what is in our opinion, poor security hygiene, by failing to isolate the filesystems of bots. This allows any user hosting with Kairo hosting to access all files, including token and database connection details of all other bots hosted by this provider. This is a major security risk, with this, we have no choice but to not recommend this host.
1x Screenshot
Stephen from the Modmail Team's Update on May 30th, 2026
> The Modmail team always attempts to work in good faith with a host when we find a security vulnerability. We have been working with this host and it appears they are making a good faith attempt to address the security vulnerabilities we have found. Even after these fixes, we still advise caution when using this host.
### baud.host
* [Website](https://baud.host)
* baud.host is a low cost hosting provider that is primarily operated by Kybo Group, a Roblox products group.
* baud.host does not allow users to provide their MongoDB Connection URI, this is not recommended as it locks users into a single host, and limits a user's ownership of their data. We were not able to conduct a test on the security of their locally hosted database, but if managed improperly, it could also be a security concern.
* baud.host uses Stripe for payment verification, however, appears to use their own processing flow, instead of the one provided by Stripe. We were unable to conduct a test on security, but this could be a security concern.
* Kybo Group claims compliance with HIPAA, GDPR, DPDPA, with an ISO27001, PCI DSS, SOC 1 Type 2, and SOC 2 Type 2 certifications, however, attempts to verify this have failed. You can conduct your own certification search with the [IAF](https://www.iafcertsearch.org/search/certified-entities?search=Kybo%20Group).
* Some users have reported features in latest updates not working with this host.
{% hint style="danger" %}
### Why These Are Not Recommended
These hosts generally:
* Use **shared or oversold Pterodactyl setups**
* Offer **free or ultra-low-cost tiers** with limited resources
* Experience **rate limits, sleep periods, or unresponsive containers**
* Provide **no control over environment configuration**
* Hide **legal information regarding their business or company**
If you value stability, security, and consistent uptime, avoid free or oversold shared hosts.\
Refer to [Choosing a Host](/choose-host) for guidance on reliable alternatives.
{% endhint %}
# Installation
Modmail hosting and installation guide.
Modmail is a self-hosted bot. This unfortunately means that there's **no** public bot invite. Due to the inner workings of the bot and its highly customisable interfaces, you will need to host your own dedicated Modmail bot.
This section provides setup instructions for Modmail on many hosting methods, both [**free**](#user-content-fn-1)[^1] **and paid**.
Here are the basic requirements for hosting your Modmail bot. You will find instructions on obtaining and using them in later sections.
* **A Discord account.**
You will need to create a Discord bot under your account.
* **A MongoDB database instance.**
Modmail will store its internal data to this database.
* **A hosting server.**
To keep Modmail running 24/7 in your server.
* **A Desktop Notepad, Notes, TextEdit, etc.**
Anywhere you can copy and paste to temporary store some texts while we set up the bot.
{% hint style="warning" %}
**Note:** There are two components for Modmail: the bot component and the Logviewer component. You will need **both** to take full advantage of Modmail.
{% endhint %}
## Create a Discord bot
The first step in setting up Modmail is to create a Discord bot.
Head over to the [**Discord Developer Portal**](https://discordapp.com/developers/applications/) and create a new application.
Click New Application from the homepage.
Choose a name for your bot, then click Create.
Once you created a new application, head over to the **Bot** tab and create a new bot.
Navigate to the Bot tab on the sidebar. On this page, you can also edit the About Me section of your bot.
Click Add bot to create the bot.
Click Yes, do it! to confirm your choice.
After adding a bot, reset the token, then copy and store the newly generated token in your Notepad for later.
Click on Reset Token then confirm with Yes, do it! Here you can also set your bot's profile picture.
Click Copy then store the copied token somewhere safe for later steps.
{% hint style="danger" %}
**Make sure to keep this token private!** Anyone who has this token can control (or "hack") your bot and potentially cause malicious damage. If you feel that your token has been leaked, click on **Reset Token** immediately to invalidate the old token and generate a new one. Don't forget to also update your Modmail configs with your new token.
{% endhint %}
Next, we need to change some bot settings. Toggle **off** *public bot*, then toggle **on** both *server members intent* **and** *message content intent*. Remember to click on **Save Changes**.
Toggle off public bot, toggle on server members intent, and toggle on message content intent. Afterwards, click Save Changes to apply the changes. Your on/off toggles should appear similar to this screenshot.
Why do I need to do this?
Disabling *public bot* prevents other users from inviting your bot. Your bot may not behave appropriately if it's present in other servers.
Enabling *server members intent* allows Modmail to view your server's members list and efficiently populate the bot's internal cache.
Enabling *message content intent* allows bot commands to function since Modmail doesn't use slash commands.
What about *presence intent*? It is not needed for Modmail, but it may be required for specialized plugins. We recommend keeping this toggled off to save computational resources.
### Inviting the bot
Navigate back to the **General Information** tab and copy the application ID.
Click Copy to copy the application ID. This is also known as your "Bot ID".
Using the following URL as template, replace `YOUR-ID-HERE` with the ID you just copied. Do not change anything else! Open a new browser tab and go to that URL.
{% code overflow="wrap" %}
```url
https://discord.com/oauth2/authorize?scope=bot&permissions=416075476184&client_id=YOUR-ID-HERE
```
{% endcode %}
Discord should prompt you to choose a server to invite your bot, followed by a list of permissions. Scroll to the bottom and click **Authorize**.
Choose your server to invite, then click Continue.
Scroll to the bottom and click Authorize. Don't un-check any permissions. Only Administrator is optional.
{% hint style="info" %}
You **must leave on** all permissions excepted for *Administrator* (optional). However, we recommend allowing *Administrator* during the setup process for ease of setup and to avoid complications with Discord permissions. Once you have fully setup and began to use the bot, you should restrict permissions to only those necessary.
{% endhint %}
Do you have a separate staff server?
If you manage a large server where you have a separate server for communication among your team, Modmail supports directing threads into the staff server instead of your main (public) server. (In our docs, when we refer to "mailbox server" or "inbox server" we are referring to this server that your threads are created in.)
You will need to invite your Modmail bot to **both** your main (public) server and your staff server using the same invite link above.
{% hint style="info" icon="location-dot" %}
You can add your Modmail bot to multiple different servers if you manage multiple. For example if you have a primary server, a gaming focused server, and a staff server. All threads will go to your staff server, but can be submitted by members of any of your servers. However, please note, that there is reduced functionality when using this approach.
{% endhint %}
Your bot should now be **offline** in your server. Congratulations, that's as expected! You have successfully created a Discord bot. The next step is to [create a MongoDB database](#create-a-mongodb-database).
## Create a MongoDB database
Modmail uses MongoDB to store its internal configurations and log histories. You must create a MongoDB database in order to use Modmail.
We will be using [MongoDB Atlas](https://www.mongodb.com/atlas), which provides us with a free 512MB storage share, more than enough for Modmail. *If you are concerned about storage space, this free cluster will last you around 300k log entries, or around 3 million messages, it is extremely rare to hit this limit, even in some of the biggest and busiest servers.*
{% hint style="info" %}
Throughout this entire section, you may find that exact page layouts, icons, and buttons have been changed or relocated on the screen. This is not a problem and will not stop you from deploying Modmail. Simply look at the page being displayed, look at the screenshot, and you will be able to find what you need with minimal complication.
MongoDB Atlas significantly alters their user interface on an overly-frequent basis, and the Modmail team does not have the time or bandwidth to take new screenshots to reflect the sometimes multiple times per month changes.
{% endhint %}
### Requirements
* No credit card required.
* An email account.
Head over to [MongoDB Atlas](https://www.mongodb.com/cloud/atlas/register) and register for a free account:
{% embed url="" %}
MongoDB Atlas registration page.
{% endembed %}
Fill in with your info, then click Create your Atlas account. Optionally, you can sign up with Google.
You will need to confirm your email. Open your confirmation email in the same browser.
Once you confirmed your email, you will be greeted by the MongoDB welcome introduction, asking you to "tell us a few things about yourself and your project". You can answer these questions honestly or however you like.
In the next step for "deploy a cloud database", choose the **Shared** option. Any recommended region (free regions) are fine. Make sure the **Cluster Tier** is set to **M0 Sandbox** and the price shows as **FREE**.
Don't see this page?
It's possible that you verified your email in a different browser session, or you manually signed in to MongoDB Atlas.
In this case, you can still follow the same steps below, but first click **Build a Database**:
Choose the free Shared option and click Create.
Make sure Shared is selected, then choose any of the "recommended region".
Make sure Cluster Tier is set to M0 Sandbox. The Cluster Name doesn't matter. Click Create Cluster.
On the following **Security Quickstart** page, do the following:
1. Authentication method: *Username and Password*
Username: `modmail` *(You can use anything you wish for this field, however, keep it short and avoid any special characters. For most users, we recommend keeping `modmail`.)*
Password: Click **Autogenerate Secure Password** - don't type your own password!
2. Copy and **save the password** in your Notepad, you will need this for later.
From now on, we will be referring to these credentials as the *database username* and *database password*.
3. Click **Create User**.
4. Scroll down, we will be connecting from: *My Local Environment*
5. Set IP address as **`0.0.0.0/0`** and anything for the description.
**You must** set the IP address exactly to this, unless you know what you're doing. **Do not** set it to anything else or click add my current IP address. This allows Modmail to connect to your database.
6. Click **Add Entry**.
You can now click **Finish and Close** on the bottom. Your page should look similar to this:
Click Autogenerate Secure Password, copy and save the database password, then click Create User.
Set IP Address to 0.0.0.0/0, then click Add Entry.
Next, we will need to generate a *MongoDB connection string*. Simply click **Connect** on the main dashboard, choose **Connect your application**, then copy the **connection string** (the default driver is fine) and paste it into your Notepad.
Click Connect on the main dashboard.
Choose Drivers.
Copy the connection string.
If you followed all the steps so far, your Notepad should contain three lines: the bot token, the database password, and the MongoDB connection string. For example:
{% code title="My Notepad" %}
```
My bot token: MTA3Djv3IAxNjk1NDgdKD231.G1AoUjD.5z629aKP34JKHn4v1EsdNUwdDO3MvBR9ifVES4
My database password: elAO7wF1r07pNG6u
My MongoDB connection string: mongodb+srv://modmail:@cluster0.example.mongodb.net/?retryWrites=true&w=majority
```
{% endcode %}
Finally, you will need to combine the database password with the MongoDB connection string by **replacing** the `` (including the `<>`) with the database password.
You also need to **remove** everything after `.mongodb.net` at the end of the MongoDB connection string.
This is what your Notepad should look like now:
{% code title="My Notepad (revised)" %}
```
My bot token: MTA3Djv3IAxNjk1NDgdKD231.G1AoUjD.5z629aKP34JKHn4v1EsdNUwdDO3MvBR9ifVES4
My MongoDB connection string: mongodb+srv://modmail:elAO7wF1r07pNG6u@cluster0.example.mongodb.net
```
{% endcode %}
You finished the MongoDB steps! At this point, your bot should still be **offline**. You can now proceed to the next step which is to choose your hosting method.
## Preparing your Environmental Variables
Once you have finished the previous steps, gather and save the variables listed below as they will be needed to run your bot in later steps:
* `TOKEN` - The token to run your Modmail application under your Discord bot account
* `LOG_URL` - Logviewer URL that will be used to view threads in your web browser. *Please view the below **danger** block if you do not intend on using a Logviewer.*
* `GUILD_ID` - The ID of the main Discord server that your bot will operate in.
* `MODMAIL_GUILD_ID` - **\[Optional]** The ID of the Discord server that your bot will create ticket channels in. This is only needed if you want your ticket channels to be created in a separate server, for an example, Staff Server.
* `OWNERS` - The user ID of the Discord accounts you want to set as owner for the bot. Can consist of multiple users, separated by comma.
* `CONNECTION_URI` - The URI the bot will use to connect to your MongoDB instance.
Your finished variables should look something like this:
{% code title=".env" %}
```py
TOKEN=OTY3Nzy5MzU5NjAzMzU2NzE4.GtKp_5.JOTYRwGW-LB1He5widCu73vXtmi90KxsqkmoOg
LOG_URL=https://logs.mymodmailbot.com/
GUILD_ID=1079074933008781362
OWNERS=188363246695219201,231595246213922828
CONNECTION_URI=mongodb+srv://username:password@cluster0-abcde.mongodb.net/
```
{% endcode %}
{% hint style="danger" %}
**DANGER** - `LOG_URL` Enviornment Variable without a Logviewer
*This is only relevant if you choose not to use a logviewer with your Modmail Instance, if you intend on having a fully featured instance, you can safely ignore this block.*
If you do not intend on using a Logviewer for your Modmail Instance, you must still ensure `LOG_URL` is set to a valid FQDN (Fully Qualified Domain Name). You can leave it as `example.com` or change it to anything else, but, do **not** delete the row, or set a value that is not an FQDN. `none`, `local`, `12032`, etc are **not** FQDNs.
If you set the `LOG_URL` to an invalid FQDN, Discord will not be able to render it properly and you will experience issues with thread creation.
{% endhint %}
{% hint style="success" %}
Congratulations! You have now completed all of the backend setup steps to get your Modmail ready, you can now move on to getting it deployed with the host of your choice. If you haven't chosen your host yet, check out our [Choosing a Host considerations](/choose-host).
{% endhint %}
## Hosting Modmail
Your next step is to choose one of our supported hosting method that's available and preferable to you.
Click on one of the links below to view further instructions for your preferred hosting method. Each method has their pros and cons, be sure to take them into consideration when choosing your hosting platform to run Modmail.
### [Railway](/installation/railway) (paid)
A platform as a service (PaaS) that offers relatively low cost plans, which allows you to host Modmail for little without any downtime. A credit card is required for payment. Their UI is very simple and easy for beginners to quickly deploy and run your Modmail bot on. You can learn more about their plans and pricing by clicking [here](https://railway.app/pricing).
### [Local Hosting](/installation/local-hosting-vps) (free)
If you have an old PC, a Raspberry Pi, or a Linux box that you're able to keep online 24/7, you can also host Modmail with your own machine at home. Since Modmail doesn't require intensive resources to run, you can get by with a system having as low as 1GB of RAM. Setting it up can be quite advanced but you have complete control over your bot instance. Refer to our local hosting guide supporting a few popular OSes by clicking [here](/installation/local-hosting-vps).
> A tip for Local Hosting: if you don't want to, don't know how to, or don't feel comfortable exposing your local machine to the internet for the Logviewer component of Modmail, Lorenzo from the Modmail team offers FREE logviewer hosting! Check it out [here](/installation/free-logviewer)
### [Modmail Team Hosting](https://buymeacoffee.com/modmaildev) (paid)
We offer paid hosting solution for your Modmail bot. Hosting Modmail with us costs $4-5 USD per month.
We will also fully manage your bot hosting for you, so you don't need to worry about upgrading or setting up your own host server. Refer to our [Patreon Hosting here](https://buymeacoffee.com/modmaildev).
See guide [Modmail Panel Hosting](/installation/modmail-panel)
### [modmail.lvh.lol](https://modmail.lvh.lol) (paid)
Run by a member of our community, this hosting provider has a purpose built software stack for hosting Modmail, logviewer not included.
See guide [Modmail Panel Hosting](/installation/modmail-panel).
### [Heroku](/installation/heroku) (paid)
Another popular PaaS that's used to be free. However, their recent pricing adjustments, it now costs $5-7 USD per month to host Modmail.
If you are currently a higher-education student, you may be eligible for the first year free with their [student offer](https://www.heroku.com/github-students). Refer to our Heroku installation guide by clicking [here](/installation/heroku).
### [Cloud Server / VPS](/installation/local-hosting-vps) (paid)
Apart from [Patreon hosting](#modmail-patreon-paid), hosting on a cloud server / VPS is the most reliable hosting method. Rent a virtual server from any reputable hosting provider of your choice for roughly $4-10 USD per month (price varies), and you'll be able to install Modmail onto the server.
This method is a lot more "involved" than other solutions. If you're not comfortable with configuring remote Linux environments, we recommend you to choose a different option. For this method, you will need to refer to our Local hosting installation guide [here](/installation/local-hosting-vps) and choose your desired OS.
## Community Guides
{% hint style="warning" %}
Community guides are not verified by the Modmail team, so use them at your own risk.
{% endhint %}
If you're not satisfied with the options listed above, some of our community members have created their own installation guides for Modmail on various other hosting platforms. Keep in mind that Modmail support staff may not be able to assist you much with community-made guides. Feel free to check them out by clicking the link below.
{% content-ref url="/pages/izr60wOyNeGd71HHxIno" %}
[Community Guides](/installation/community-guides)
{% endcontent-ref %}
[^1]: Some free options require a credit card for verification.
# Local Hosting / VPS
Hosting on the cloud or on your own computer.
## General Requirements
* A supported hardware to comfortably run your chosen OS or a reliable VPS provider.
* Stable internet access and uptime for your machine or host.
* You have completed the initial steps in the [Installation](/installation) page.
More OS-specific requirements will be listed on their specific installation page, you are free to choose a supported OS of your choice from the list below.
## Choose your Operating System
* [Windows](/installation/local-hosting-vps/windows)
* [MacOS](/installation/local-hosting-vps/macos)
* [Docker](/installation/local-hosting-vps/docker)
* [Ubuntu](/installation/local-hosting-vps/ubuntu)
* [Debian](/installation/local-hosting-vps/debian)
* [Fedora](/installation/local-hosting-vps/fedora)
* [Alma Linux](/installation/local-hosting-vps/almalinux)
* [CentOS](/installation/local-hosting-vps/almalinux)
* [Raspberry Pi OS](/installation/local-hosting-vps/debian)
* See the **Raspberry Pi OS Steps** section to ensure a proper installation.
## Logviewer
You can also self-host logviewer by following the guides below.
* [Logviewer](/installation/local-hosting-vps/logviewer)
* [Patreon Logviewer](/installation/local-hosting-vps/patreon_logviewer)
# Windows
Deploy Modmail on a Windows machine.
## Prerequisites
1. Minimum 4GB of RAM\*
2. At least 2GB available disk space.
3. Supported Windows version: Windows 11
{% hint style="info" %}
Note that while it is possible to run Modmail with even less memory, Windows 10 itself recommends at least 4GB. This guide assumes the lowest threshold to comfortably run Modmail without possibly running into any resource bottleneck.
{% endhint %}
{% hint style="warning" %}
It is not recommended to run Modmail with previous versions of Windows such as Windows 7, 8, 8.1, or 10 as they no longer receive important security updates, making your hosted applications significantly more prone to security vulnerabilities.
{% endhint %}
## Dependencies
We will be using the following dependencies:
* Chocolatey
* Python 3.10
* Additional Modmail requirements: [GTK for Windows](https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/)
To install these dependencies, we will be using Powershell.
Search “powershell” in the Windows start menu, right-click on it and then click “Run as administrator”.
Then run each of the following commands:
```powershell
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
choco upgrade git --params "/GitOnlyOnPath /WindowsTerminal" -y
choco upgrade python310 -y
```
After that, ensure `pip` and `pipenv` are installed and updated for Python 3.10 with:
```powershell
py -3.10 -m ensurepip --upgrade
py -3.10 -m pip install pipenv
```
After the above installation has finished, download and install the **GTK runtime for Windows** by [clicking here](https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases/latest).
## Installing Bot
In any folder location of your choice, `Shift+Right Click` and click on `Open PowerShell window here`.
In your PowerShell window, run these commands to clone the official Modmail repository locally and `cd` into the folder:
```powershell
git clone https://github.com/modmail-dev/modmail
cd modmail
```
Install project dependencies inside Modmail's pipenv with:
```powershell
py -3.10 -m pipenv install
```
{% hint style="info" %}
To be able to create file named `.env` you **must** have the option to `Hide extensions for known file types` to OFF. It will not allow you to create a correctly named file with this set to on. (To turn it off, press the `...` on the File Explorer options bar, then `Options`, then `View`, and finally uncheck the option.)
{% endhint %}
Create a new file in the modmail folder named `.env` and paste in your environmental variables needed to run Modmail. Refer to the steps in the [parent Installation page](/installation#preparing-your-environmental-variables) to find where to obtain these.
Lastly, in your PowerShell window simply enter the command below to run your Modmail bot:
```powershell
py -3.10 -m pipenv run bot
```
If no error shows up, it means that your Modmail is now running correctly.
# MacOS
Deploy Modmail on a macOS machine. (Tested with Apple Silicon M2)
## Prerequisites
1. Minimum 2GB of RAM
2. At least 2GB available disk space.
3. Supported macOS version:
* MacOS 14 Sonoma (Tested)
* MacOS 11 Monterey (Tested)
## Dependencies
We will be using the following dependencies:
* Python 3.10
* Tools: `git`, `homebrew`, `bash` or `zsh`
* Additional Modmail requirements: `cairo`, `libxml2`, `libxslt`, `libffi`
{% hint style="info" %}
All code blocks should be executed in zsh or bash and line by line unless specified otherwise.
{% endhint %}
To install these dependencies, we will be using Terminal (zsh or bash):
```bash
brew install git python@3.10 cairo libxml2 libxslt libffi
pip3 install cairosvg
```
After that, install `pipenv` with:
```bash
python3.10 -m pip install pipenv
```
## Installing Bot
Clone and change directory into the Modmail folder with:
```bash
git clone https://github.com/modmail-dev/modmail
cd modmail
```
Inside the Modmail folder, install `pipenv` and its Python packages with:
python3.10 -m pipenv install --python 3.10
Create a file named `.env` with `nano` and paste all the environmental variables (secrets) needed to run the bot via right-clicking in the nano editor. Refer to the steps in the [parent Installation page](/installation#preparing-your-environmental-variables) to find where to obtain these.
```bash
cp .env.example .env
nano .env
```
After that, exit the nano editor with `Ctrl+X` and select or enter `y` when prompted to save. Press enter to maintain the exiting name of the document.
{% hint style="info" %}
If using the `nano` editor is a bit of a learning curve, you can edit the `.env` file manually with your preferred GUI-based editor like TextEdit.
{% endhint %}
After your `.env` file is ready, you can now go ahead and try running your bot with:
```bash
python3.10 -m pipenv run bot
```
If no error shows up, it means your bot is now running correctly. You can stop the bot from running with `Ctrl+C` to continue using your terminal.
# Docker
Deploy Modmail on Docker.
{% hint style="info" %}
Docker is considered an advanced setup, it is recommended that you understand how Docker works before deciding to use this method.
{% endhint %}
A simple illustration explaining how Docker works
## Prerequisites
* Supported OS for Docker
* Docker Engine
* Docker Compose
## Installing Docker Engine
Docker has their own installation page for popular Linux-based distros, read them by visiting the link below:
{% embed url="" %}
If you're on a desktop environment, refer to the "Desktop" section of their documentation as Docker Desktop also comes with nice GUI that you manage your deployments with.
For VPS and servers, refer to the "Server" section as you will be needed to learn the CLI commands to run Modmail with Docker.
After the installation process has finished, you can try running the commands below in your terminal to see if **Docker** and **Docker Compose** has been installed successfully:
```docker
docker --version
docker compose version
```
{% hint style="info" %}
You may need to change your Docker Compose command to `docker-compose --version` depending on the version you have installed.
{% endhint %}
## Running the official image for Modmail
You can pull the latest official image from Modmail repository by using the following command:
```docker
docker pull ghcr.io/modmail-dev/modmail:master
```
This will take some time depending on the speed of your network. It will also update the already existing image if you have previously pulled the same image before.
After that, you can run the bot as a container with the following command:
```docker
docker run -d --name modmail \
--env-file /path/to/.env \
--restart always ghcr.io/modmail-dev/modmail:master
```
Make sure to change `/path/to/.env` to the location of the `.env` file containing all the variables that you want the bot to start with. Refer to the steps in the [parent Installation page](/installation#preparing-your-environmental-variables) to find where to obtain these.
After deploying, you can view the logs of your currently running Modmail container with the following command:
```docker
docker logs modmail
```
You can stop your running Modmail container with:
```
docker stop modmail
```
Stopping the container does not remove the container files, so you can start it back up with:
```
docker start modmail
```
If you want to stop and remove the container completely, you can do so with:
```
docker rm -f modmail
```
The `-f` will forcefully remove and delete the container even if it's currently running. You can omit the flag if the container is already stopped.
## Building the image locally
You can also build the image locally on your machine if the repository files are already in your machine. In your Modmail project folder, simply run the build command below:
```
docker build . -t myname/modmail:latest
```
The `.` in the command will use the `Dockerfile` in the Modmail repository as the build steps. The `-t` flag will specify the image tag so it's easier for us to differentiate between multiple images in our system. Verify if the image is successfully built with the following command:
```
docker images
```
You should be able to see the tag we just used in the list:
Now you can use the `docker run` command to run your bot using your locally-built image:
```docker
docker run -d --name modmail \
--env-file /path/to/.env \
--restart always myname/modmail:latest
```
## Updating on Docker
Auto-update is disabled when running Docker as Docker container state is not persistent across restarts. To update your bot, you will need to update the base image by running the `docker pull` command in the previous step: [Running the official image for Modmail](#running-the-official-image-for-modmail) if your image is based from the official repository. After that, you must recreate your container using the `docker rm` and `docker run` command again.
If your image is created locally, simply replace the `docker pull` command with `git pull` and rebuilding your image again.
To automate this process on Docker, you can look into running [Watchtower](https://containrrr.dev/watchtower/) which will auto-update your containers whenever a new image is pushed on the remote repository. Please refer to their documentation for guide and configuration.
# Ubuntu
Deploy Modmail on an Ubuntu server.
{% hint style="warning" %}
For safety reasons, **DO NOT** install Modmail with a root user. A misbehaving or malicious plugin installed on your Modmail bot can easily access your entire system. If you are unsure how to create a new user on Linux, see [DigitalOcean’s tutorial: How To Create a New Sudo-enabled User](https://www.digitalocean.com/community/tutorials/how-to-create-a-new-sudo-enabled-user-on-ubuntu-20-04-quickstart).
{% endhint %}
## Prerequisites
1. Root access (**`sudo`**).
2. Minimum 1GB of RAM
3. At least 2GB available disk space.
4. Supported releases:
* Ubuntu 18.04 LTS (Bionic Beaver)
* Ubuntu 20.04 LTS (Focal Fossa)
* Ubuntu 22.04 LTS (Jammy Jellyfish)
## Dependencies
We will be using the following dependencies:
* Python 3.10
* Tools: `git`, `wget`, `nano`, `software-properties-common`
* Additional Modmail requirements: `libcairo2-dev`, `libffi-dev`, `g++`
{% hint style="info" %}
All code blocks should be executed in bash and line by line unless specified otherwise.
{% endhint %}
To install these dependencies, we will be using **`apt`**.
We recommend adding the `deadsnakes` ppa to install Python 3.10:
```bash
sudo apt update
sudo apt -y install software-properties-common
sudo add-apt-repository -y ppa:deadsnakes/ppa
```
Now install the pre-requirements with `apt`, you can copy and run these 3 lines at once:
```bash
sudo apt -y install python3.10 python3.10-dev python3.10-venv python3-pip \
libcairo2-dev libffi-dev g++ \
git nano
```
After that, install `pipenv` with:
```bash
python3.10 -m pip install pipenv
```
Failed to install Python 3.10?
You can manually compile Python instead of adding using the Deadsnakes PPA. Compiling Python may take a while (est. 5-10 minutes). Copy and run line 2-7 all at once.
{% code lineNumbers="true" %}
```bash
sudo apt update && sudo apt upgrade -y # Update and upgrade all packages
sudo apt install -y software-properties-common \
libcairo2-dev libffi-dev g++ \
git wget nano \
build-essential zlib1g-dev libncurses5-dev \
libgdbm-dev libnss3-dev libssl-dev \
libreadline-dev libffi-dev libsqlite3-dev libbz2-dev
wget https://www.python.org/ftp/python/3.10.9/Python-3.10.9.tgz
tar xzf Python-3.10.9.tgz
cd Python-3.10.9
./configure --enable-optimizations
make altinstall
```
{% endcode %}
## Installing Bot
Clone and change directory into the Modmail folder with:
```bash
git clone https://github.com/modmail-dev/modmail
cd modmail
```
Inside the Modmail folder, Install `pipenv` and its Python packages with:
python3.10 -m pipenv install --python 3.10
Create a file named `.env` with `nano` and paste all the environmental variables (secrets) needed to run the bot via right-clicking in the nano editor. Refer to the steps in the [parent Installation page](/installation#preparing-your-environmental-variables) to find where to obtain these.
```bash
nano .env
```
After that, press `Ctrl+O` and `Enter` to save your changes. Exit the `nano` editor with `Ctrl+X`.
{% hint style="info" %}
If using the `nano` editor is a bit of a learning curve, you can always FTP into your server using software like [WinSCP](https://winscp.net/eng/index.php) to edit the `.env` file manually with your preferred GUI-based editor like Notepad.
{% endhint %}
After your `.env` file is ready, you can now go ahead and try running your bot with:
```bash
python3.10 -m pipenv run bot
```
If no error shows up, it means your bot is now running correctly. You can stop the bot from running with `Ctrl+C` to continue using your terminal.
# Debian
Deploy Modmail on Debian / Raspberry Pi OS.
{% hint style="warning" %}
For safety reasons, **DO NOT** install Modmail with a root user. A misbehaving or malicious plugin installed on your Modmail bot can easily access your entire system. If you are unsure how to create a new user on Linux, see [DigitalOcean’s tutorial: How To Create a New Sudo-enabled User](https://www.digitalocean.com/community/tutorials/how-to-create-a-new-sudo-enabled-user-on-ubuntu-20-04-quickstart).
{% endhint %}
Raspberry Pi OS 11 Bullseye and Raspberry Pi OS 10 Buster are based on Debian 11 Bullseye and Debian 10 Buster respectively so you can essentially follow this guide if you're running any of the OS mentioned above.
## Prerequisites
1. Root access (**`sudo`**).
2. Minimum 1GB of RAM
3. At least 2GB available disk space.
4. Supported releases:
* Debian 11 Bullseye
* Debian 10 Buster
* Raspberry Pi OS 11 Bullseye
* Raspberry Pi OS 10 Buster
## Dependencies
* Python 3.9 / 3.10
* Tools: `git`, `wget`, `nano`
* Additional Modmail requirements: `libcairo2-dev`, `libffi-dev`, `g++`
{% hint style="info" %}
All code blocks should be executed in bash and line by line unless specified otherwise.
{% endhint %}
To install these dependencies, we will be using **`apt`**.
### Raspberry Pi OS Steps
{% hint style="info" %}
By default, [Raspberry Pi OS](https://www.raspberrypi.com/software/operating-systems/) is missing some libraries to use modmail. Please run the following command to be able to use modmail. `sudo apt update && sudo apt upgrade -y && sudo apt install libjpeg8-dev`
{% endhint %}
### **Debian 11 Bullseye /** Raspberry Pi OS 11 Bullseye
```bash
sudo apt update
sudo apt -y install python3 python3-dev python3-venv python3-pip libcairo2-dev libffi-dev g++ git wget nano
```
At the time of writing, this will install Python 3.9 from Debian's repository.
### **Debian 10 Buster /** Raspberry Pi OS 10 Buster
You will need to manually compile Python 3.10 from source. Compiling Python may take a while (est. 5-10 minutes). Make sure to run line 2-7 all at once.
{% code lineNumbers="true" %}
```bash
sudo apt update && sudo apt upgrade -y # Update and upgrade all packages
sudo apt install -y software-properties-common \
libcairo2-dev libffi-dev g++ \
git wget nano \
build-essential zlib1g-dev libncurses5-dev \
libgdbm-dev libnss3-dev libssl-dev \
libreadline-dev libffi-dev libsqlite3-dev libbz2-dev
wget https://www.python.org/ftp/python/3.10.9/Python-3.10.9.tgz
tar xzf Python-3.10.9.tgz
cd Python-3.10.9
./configure --enable-optimizations
sudo make altinstall
```
{% endcode %}
After that, ensure `pip` is installed and updated for Python 3.10 with:
```
python3.10 -m ensurepip --upgrade
```
Then **log out and log back in** to continue the installation steps.
## Installing Bot
Clone and change directory into the Modmail folder with:
```bash
git clone https://github.com/modmail-dev/modmail
cd modmail
```
Inside the Modmail folder, Install `pipenv` and the bot dependencies with:
```bash
python3.9 -m pip install pipenv
python3.9 -m pipenv install --python 3.9
```
{% hint style="info" %}
Replace `3.9` with `3.10` on the command above if you followed [Debian 10 Buster](#debian-10-buster-raspberry-pi-os-10-buster) method previously.
{% endhint %}
Create a file named `.env` with `nano` and paste all the environmental variables (secrets) needed to run the bot via right-clicking in the nano editor. Refer to the steps in the [parent Installation page](/installation#preparing-your-environmental-variables) to find where to obtain these.
```bash
nano .env
```
After that, press `Ctrl+O` and `Enter` to save your changes. Exit the `nano` editor with `Ctrl+X`.
{% hint style="info" %}
If using the `nano` editor is a bit of a learning curve, you can always FTP into your server using software like [WinSCP](https://winscp.net/eng/index.php) to edit the `.env` file manually with your preferred GUI-based editor like Notepad.
{% endhint %}
After your `.env` file is ready, you can now go ahead and try running your bot with:
```bash
python3.9 -m pipenv run bot
```
{% hint style="info" %}
Replace `3.9` with `3.10` on the command above if you followed[ Debian 10 Buster](#debian-10-buster-raspberry-pi-os-10-buster) method previously.
{% endhint %}
If no error shows up, it means your bot is now running correctly. You can stop the bot from running with `Ctrl+C` to continue using your terminal.
# Fedora
Deploy Modmail on a Fedora server.
{% hint style="warning" %}
For safety reasons, **DO NOT** install Modmail with a root user. A misbehaving or malicious plugin installed on your Modmail bot can easily access your entire system. If you are unsure how to create a new user on Linux, see [DigitalOcean’s tutorial: How To Create a New Sudo-enabled User](https://www.digitalocean.com/community/tutorials/how-to-create-a-new-sudo-enabled-user-on-ubuntu-20-04-quickstart).
{% endhint %}
## Prerequisites
1. Root access (**`sudo`**).
2. Minimum 1GB of RAM
3. At least 2GB available disk space.
4. Supported releases:
* Fedora 38
* Fedora 37
* Fedora 36
* Fedora 35
## Dependencies
* Python 3.10
* Tools: `git`, `wget`, `nano`
* Additional Modmail requirements: `g++`
{% hint style="info" %}
All code blocks should be executed in bash and line by line unless specified otherwise.
{% endhint %}
Fedora Linux 35 and above has all required packages available in official repositories. Install them with `dnf`.
```bash
sudo dnf -y install python310 git nano g++ gtk3
```
And then, make sure `pip` is installed for Python 3.10 with:
```bash
python3.10 -m ensurepip --upgrade
```
## Installing Bot
Clone and change directory into the Modmail folder with:
```bash
git clone https://github.com/modmail-dev/modmail
cd modmail
```
And then, install `pipenv` and the bot dependencies with:
Create a file named `.env` with `nano` and paste all the environmental variables (secrets) needed to run the bot via right-clicking in the nano editor. Refer to the steps in the [parent Installation page](/installation#preparing-your-environmental-variables) to find where to obtain these.
```bash
nano .env
```
After that, press `Ctrl+O` and `Enter` to save your changes. Exit the `nano` editor with `Ctrl+X`.
{% hint style="info" %}
If using the `nano` editor is a bit of a learning curve, you can always FTP into your server using software like [WinSCP](https://winscp.net/eng/index.php) to edit the `.env` file manually with your preferred GUI-based editor like Notepad.
{% endhint %}
After your `.env` file is ready, you can now go ahead and try running your bot with:
```bash
python3.10 -m pipenv run bot
```
If no error shows up, it means your bot is now running correctly. You can stop the bot from running with `Ctrl+C` to continue using your terminal.
# Alma Linux
Deploy Modmail on RHEL / Alma Linux / CentOS server.
{% hint style="warning" %}
For safety reasons, **DO NOT** install Modmail with a root user. A misbehaving or malicious plugin installed on your Modmail bot can easily access your entire system. If you are unsure how to create a new user on Linux, see [DigitalOcean’s tutorial: How To Create a New Sudo-enabled User](https://www.digitalocean.com/community/tutorials/how-to-create-a-new-sudo-enabled-user-on-ubuntu-20-04-quickstart).
{% endhint %}
Alma Linux 8, 9 and CentOS Stream 8, 9 are based on Red Hat Enterprise Linux (RHEL) 8 and 9 respectively so you can essentially follow this guide if you're running any of the OS mentioned above.
## Prerequisites
1. Root access (**`sudo`**).
2. Minimum 1GB of RAM
3. At least 2GB available disk space.
4. Supported releases:
* Alma Linux 9
* Alma Linux 8
* CentOS Stream 9
* CentOS Stream 8
* Red Hat Enterprise Linux (RHEL) 9
* Red Hat Enterprise Linux (RHEL) 8
## Dependencies
* Python 3.9
* Tools: `git`, `nano`
{% hint style="info" %}
All code blocks should be executed in bash and line by line unless specified otherwise.
{% endhint %}
### RHEL 9 / Alma Linux 9 / CentOS Stream 9
RHEL 9 and its derivatives have all required packages available in official repositories. Install them with `dnf`:
```bash
sudo dnf -y install python39 git @development nano
```
### RHEL 8 / Alma Linux 8 / CentOS Stream 8.4-8.x
RHEL 8 and its derivatives have all required packages available in official repositories. Install them with `dnf`:
```bash
sudo dnf -y update
sudo dnf -y group install development
sudo dnf -y install python39 python39-pip python39-devel nano git
```
## Installing Bot
Clone and change directory into the Modmail folder with:
```bash
git clone https://github.com/modmail-dev/modmail
cd modmail
```
Inside the Modmail folder, ensure `pip` is installed correctly and is defaulting to Python 3.9 with:
```bash
python3.9 -m ensurepip --upgrade
```
And then, install `pipenv` and the bot dependencies with:
```bash
python3.9 -m pip install pipenv
python3.9 -m pipenv install --python 3.9
```
Create a file named `.env` with `nano` and paste all the environmental variables (secrets) needed to run the bot via right-clicking in the nano editor. Refer to the steps in the [parent Installation page](/installation#preparing-your-environmental-variables) to find where to obtain these.
```bash
nano .env
```
After that, press `Ctrl+O` and `Enter` to save your changes. Exit the `nano` editor with `Ctrl+X`.
{% hint style="info" %}
If using the `nano` editor is a bit of a learning curve, you can always FTP into your server using software like [WinSCP](https://winscp.net/eng/index.php) to edit the `.env` file manually with your preferred GUI-based editor like Notepad.
{% endhint %}
After your `.env` file is ready, you can now go ahead and try running your bot with:
```bash
python3.9 -m pipenv run bot
```
If no error shows up, it means your bot is now running correctly. You can stop the bot from running with `Ctrl+C` to continue using your terminal.
# Logviewer
Hosting the logviewer on the cloud or on your own computer.
## Prerequisites
This logviewer hosting tutorial is written assuming you have already set up your bot on one of the supported operating systems.
{% hint style="warning" %}
The logviewer can be set up using your local pc or homeserver. However it is higly recommended to run the logviewer on a vps or different cloud based service to avoid security issues. To let staff members access the logviewer (which is a popular usecase) you need to expose ports to the public internet which can be risky for your router and it´s local network. There are also several other issues that can occur. Please only set up your logviewer on your local network **if you can take full responsibility and 100% know what you are doing.**
{% endhint %}
## Dependencies
* Python 3.11
* Tools: `git`, `wget`, `nano`
## Downloading the files
* You must have git installed on your system. If you do not, run `sudo apt install git` to install it.
You can download the logviewer files by running the following command:
```bash
git clone https://github.com/modmail-dev/logviewer logviewer
```
Once done, you can use \`cd logviewer\` to enter the directory.
## Installing the dependencies
First, install pipenv by running the following command:
* Pipenv must be installed. Since this is also used for the bot, you can skip this step if you have already installed it. You may neeed to use a different command to access your python installation depending on your operating system and python configuration.
```bash
python -m pip install pipenv
```
Installing the dependencies is done by running the following command:
```bash
pipenv install
```
## Configuring the .env
To configure the `.env` file, you can use the following command:
```bash
nano .env.example
```
This will open the example `.env` file in nano. You can then edit the file with your info. You will need to enter the same mongo URI as your bot uses. The rest of the configs can be left to the default values, unless you have a specific reason to change them.
Then save the file and exit nano by pressing `ctrl + x`, then `y`, change the name from `.env.example` to `.env` and then `enter`.
## Running the logviewer
Now you can start the logviewer with the following command
```bash
sudo pipenv run logviewer
```
## (Optional) Keep logviewer running in the background with pm2
Pm2 can keep your logviewer automatically online in the background even if you close your terminal. To install pm2, run the following command:
```bash
sudo apt install npm -y && sudo npm i pm2 -g
```
Once installed, you can start the logviewer with pm2 by running the following command:
```bash
sudo pm2 start logviewer.sh --name "logviewer" && sudo pm2 save
```
More info on how to use pm2 can be found [on pm2's website](https://pm2.keymetrics.io/docs/usage/quick-start/).
# Patreon Logviewer
Hosting the patreon logviewer on the cloud or on your own computer.
{% hint style="danger" %}
The Modmail team is no longer supporting or encouraging the self-hosting of the Patreon logviewer. This guide is saved for archive reasons only. This guide does not have any use to nearly any users. If you want to self-host the normal logviewer, this is supported. Please see the [Logviewer Hosting Guide](/installation/local-hosting-vps/logviewer).
{% endhint %}
Archived Patreon Logviewer Guide
This logviewer hosting tutorial is written assuming you have already set up your bot and are running Ubuntu 20.04-22.04.
### Setting up OAuth2
To set up OAuth2, you need to set a few settings in your Discord Developer Portal. First, head to the [Discord Developer Portal](https://discord.com/developers/applications) and select your modmail bot application. Then go to "OAuth2" and "General"
First, copy the Client ID and Client Secret. You will need these later when filling in the `.env`. Then, set a redirect URL to `https://yourlogviewer.com/callback`, with the url being changed to the url of your logviewer. Finally, click save.
### Downloading the files
* You must have git installed on your system. If you do not, run `sudo apt install git` to install it.
Due to the logviewer premium repo being private, you will first need to set up a personal access token to clone the repo. To do this, follow the steps below.
* Open github in your browser
* When logged in, click your name in the top right and go to 'settings'
* On the left, click 'Developer settings'
* On the left, click 'Personal access tokens' and then 'Tokens (classic)'
* Click 'Generate new token'
* Give the token a name and select the 'repo' scope
* Copy the token and save it somewhere safe
You can download the logviewer files by running the following command:
```bash
git clone https://github.com/modmail-dev/logviewer-premium logviewer
```
You will be prompted for your username and password. Enter your github username and the personal access token you just created.
Once done, you can use \`cd logviewer\` to enter the directory.
### Installing the dependencies
First, install pipenv by running the following command:
* Pipenv must be installed. Since this is also used for the bot, you can skip this step if you have already installed it.
```bash
python -m pip install pipenv
```
Installing the dependencies is done by running the following command:
```bash
pipenv install
```
### Configuring the .env
To configure the `.env` file, you can use the following command:
```bash
nano .env.example
```
This will open the example `.env` file in nano. You can then edit the file with your info. Besides the normal logviewer config, you will also need to add your bot's token and the client ID and secret you copied earlier.
You will need to enter the same mongo URI as your bot uses. The rest of the configs can be left to the default values, unless you have a specific reason to change them.
Then save the file and exit nano by pressing `ctrl + x`, then `y`, change the name from `.env.example` to `.env` and then `enter`.
### Running the logviewer
Now you can start the logviewer with the following command
```bash
sudo pipenv run logviewer
```
### Whitelisting users
To allow people to view the logviewer, you will have to whitelist them. To do this, you can use the following command in discord where your modmail bot is: `?oauth whitelist roleID` or `?oauth whitelist userID`.
### (Optional) Keep logviewer running in the background with pm2
Pm2 can keep your logviewer automatically online in the background even if you close your terminal. To install pm2, run the following command:
```bash
sudo apt install npm -y && sudo npm i pm2 -g
```
Once installed, you can start the logviewer with pm2 by running the following command:
```bash
sudo pm2 start logviewer.sh --name "logviewer" && sudo pm2 save
```
More info on how to use pm2 can be found [on pm2's website](https://pm2.keymetrics.io/docs/usage/quick-start/).
# Setting up Auto-Restart (Linux)
Ways to setup auto restart for your bot on Linux hosts.
{% tabs %}
{% tab title="PM2" %}
PM2 is a process manager originally intended for Node.js but can also be used with Python applications, such as our Modmail bot and Logviewer. To use \`pm2\`, we will need to install Node Package Manager (\`npm\`).
**Installing `pm2` Using `apt` (Ubuntu, Debian, etc):**
```bash
sudo apt install npm -y && sudo npm i pm2 -g
```
**Installing `pm2` using `dnf` (Fedora, Alma Linux, etc):**
```bash
sudo dnf -y install npm && sudo npm i pm2 -g
```
Then, in the Modmail folder, start the Modmail process in the background with:
```
pm2 start modmail.sh --name "modmail"
```
You can see the logs of your Modmail process with:
```
pm2 logs modmail
```
And then, to make sure that `pm2` stays active and persistent between machine restarts, run the following commands:
```bash
pm2 save && pm2 startup
```
Here's some of the other PM2 commands for future reference:
````bash
pm2 restart modmail
pm2 reload modmail
pm2 stop modmail
pm2 delete modmail
pm2 list
```
`systemd` is a built-in service manager for most Linux systems. It's primary used to manage background applications and services and to make applications auto-restart on crash and run on system startup.
We will be using `systemd` for Modmail by making a service file for our bot.
In order to create the service file, you will first need to know three things, your Linux `username`, your Modmail folder location as `modmail_path` and your Pipenv location as `pipenv_path`.
First, your Linux `username` can be fetched with the following command:
```bash
whoami
````
You can get your `pipenv_path` with:
```
whereis pipenv
```
Now, using `nano`, create a service file for systemd with:
```bash
sudo nano /etc/systemd/system/modmail.service
```
and paste in the contents below, replacing `username`, `modmail_path` and `pipenv_path` with yours respectively. `Ctrl+O` and `Enter` to save. `Ctrl+X` to exit the nano editor.
{% code title="modmail.service" %}
```bash
[Unit]
Description=Modmail bot
After=network.target
[Service]
User=username # replace this
Group=username # replace this
Restart=always
RestartSec=10
Type=simple
WorkingDirectory=modmail_path # replace this
ExecStart=pipenv_path run python bot.py # replace pipenv_path only
[Install]
WantedBy=multi-user.target
```
{% endcode %}
Now, start your Modmail bot with:
```bash
sudo systemctl start modmail
```
If everything goes correctly, you should see your bot online. You can also view the logs of your systemd process with:
```bash
sudo journalctl -eu modmail
```
With that said, go ahead and enable your Modmail service to auto-restart after crash and reboot with:
```bash
sudo systemctl enable modmail
```
If in the future you need to stop and disable your Modmail service, you can do so with:
````bash
sudo systemctl stop modmail
sudo systemctl disable modmail
```
````
{% endtab %}
{% endtabs %}
# Setting up Auto-Restart (Windows)
Ways to setup auto restart for your bot on Windows hosts.
## Using PM2 on Windows
Todo:
## Using NSSM on Windows
To have the bot auto-restart on crash or system reboot, we will be using `nssm` by making a service for our bot application.
First, find the Python path of your Modmail pipenv by running `pipenv shell` and `which python` in your Modmail folder. Copy the path that appears in your terminal and paste it in the first line of our next step.
Second, create a file named `modmail.bat` in your modmail directory with the following contents, replacing `python_path` with the one you copied previously and `python.exe` with `activate.bat`:
```batch
call python_path
call python bot.py
```
The finished file should look something like this:
{% code title="modmail.bat" %}
```batch
call C:\Users\Raiden\.virtualenvs\modmail-oXWHQUly\Scripts\activate.bat
call python bot.py
```
{% endcode %}
Third, download `nssm` by [clicking here](http://nssm.cc/download) and downloading the file under "Latest Release".
The download will be a `.zip` file so you'll need to extract it first using your file archiver program (such as WinRAR or 7-zip). After that, find `nssm.exe` in the folder corresponding to your OS bit version (these days it should be win64) and copy it's file path:
As `nssm` itself is only a command-line program, we'll need to use our trusty Terminal to use the application to create our service. So, search up "Powershell" in your start menu, right-click it and click "Run as Administrator".
Change directory (CD) into the folder path that you copied earlier, the command should look like something like this:
```powershell
cd "C:\Users\Raiden\Downloads\nssm-2.24\win64"
```
{% hint style="info" %}
Wrapping "your folder\directory" on Windows in double quotes is necessary to make sure spaces in our file path is parsed correctly.
{% endhint %}
And then, proceed to create a new service for Modmail using `nssm` with:
```powershell
.\nssm install "Modmail"
```
A GUI will pop up where you can fill in the details needed for your Modmail service. Replace the `Path` with the path of your `modmail.bat` script and the `Startup directory` with the path of your Modmail folder as follow:
You can fill in these extra details as you see fit as it's only for your own reference:
You can also optionally specify a log file as output and error in the `I/O` tab, just be sure to create the file beforehand so you can select it in the GUI.
And finally, click "Install Service" to install your Modmail bot as a service on your Windows system.
By now you should have the service installed but not yet running. You can start it by using this command below in the open `nssm` Terminal from earlier:
```
.\nssm start modmail
```
You should be able to see your bot running if everything goes well. You can also verify the status of your Modmail service with:
```
.\nssm status modmail
```
And if you specified the log output file in your previous step, you should be able to see your current Modmail logs like so:
And that's it! Your bot will now auto-start everytime you reboot your system. You can also additionally stop and restart your service with `.\nssm stop modmail` and `.\nssm restart modmail` respectively. Refer to [NSSM Documentation](http://nssm.cc/usage) for further customization as this guide is only meant to cover the basic needs adequate for standard Modmail usage.
# Railway
Deploy Modmail on Railway PaaS.
## Railway
### What is Railway?
Railway is a deployment platform where you can provision infrastructure, develop with that infrastructure locally, and then deploy to the cloud.
### Requirements
* A credit card.
* An email account.
* A [GitHub](https://github.com/signup) account.
* You have completed the initial steps: [invited your bot](/installation#create-a-discord-bot) and [created a MongoDB database](/installation#create-a-mongodb-database).
### Costs
Their lowest plan starts at $5 per month. Visit the [pricing](https://railway.com/pricing) page for the up-to-date pricing info.
## Deploy on Railway using Railway Templates
#### Modmail Bot:
[](https://railway.com/deploy/modmail)
#### Modmail Logviewer:
[](https://railway.com/deploy/modmail-logviewer)
Deploying via these templates makes it easier because you do not need to fork (copy) our github repository and creating the project is made a bit smoother. However if you do face issues or anything else, you may use the alternative way to deploy below. The User account creation instructions can be followed from below
### Fork our GitHub repositories
You will need to fork our repositories to deploy onto Railway.
Make sure you're logged in to [GitHub](https://github.com/). You will need to fork **two** repositories.
First we fork the Modmail repository. Head over to , leave all the settings as default, and click **Create fork**.
Create a GitHub fork for the Modmail Repository.
Next do the same for the Logviewer repository by heading over to , leave all the settings as default, and click **Create fork**.
Create a GitHub fork for the Logviewer Repository.
Next, to keep your Modmail and Logviewer up to date, you will need to install the [Pull app](https://github.com/apps/pull). Simply head over to , click **Install**, choose **Only select repositories**, then select **both** the Modmail and Logviewer repositories that you forked in the previous step.
Select both the Modmail and Logviewer forks, then click Install.
Your GitHub should now be all set. Next step, [create a Railway account](#create-a-railway-account) to deploy your bot.
### Create a Railway account
Head over to [Railway's website](https://railway.app/new) and create an account. It will ask you to create a new project, choose **Deploy from GitHub repo**. Then, you will be asked to connect your GitHub account.
{% embed url="" %}
Sign up for a new Railway account.
{% endembed %}
Choose Deploy from GitHub repo when creating a new project.
Why does it says "Your Account is Unverified"?
If your GitHub account is new or not reputable, you may be asked to verify your identify.
This unfortunately means that you will have to provide a credit card for verification. Click **Verify Account**, read and accept Railway's **Terms of Service**, then enter your credit card details. You may be temporary charged $1 USD to confirm the legitimacy of the card.
   
Next, you will be asked to **Configure a GitHub App**. You will be directed to the GitHub authentication page. Choose **Only select repositories**, then select **both** the Modmail and Logviewer repositories, as you have done before. Finally, click **Install & Authorize**.
Click Configure a GitHub App.
Select both the Modmail and Logviewer forks, then click Install & Authorize.
The next step is to deploy Modmail onto Railway. This is split into two parts. You will need to complete **both parts** to fully Modmail.
### Part 1: Deploying the Logviewer
From the [**New Project**](https://railway.app/new) page, create the project by selecting your **Logviewer** repository, then select **Add variables**.
Choose your Logviewer repository fork.
Click on Add variables. Alternatively, the following page can also be found within the project -> variables menu.
Click **New Variable**, set left to be **`CONNECTION_URI`**, then on the right, paste your revised MongoDB connection string from your Notepad (if this is new to you, [go back and read the initial steps](/installation)).
Don't add any other variables, nor use the suggested variables section. You should see a new variable named **`CONNECTION_URI`** added under variables once you're done.
Click on New Variable.
Left side: CONNECTION_URI. Right side: your MongoDB connection string. Then click + Add.
Once you've added the variable, you should see a single variable named CONNECTION_URI.
Next, go to the **Deployments** tab, look at the latest deployment, is it successful? You may need to wait up to 10 minutes. If you click the URL, you should be taken to your Logviewer homepage (see screenshot below). **Save this URL** into your Notepad as we will need it for the next step, we will be referring to this as your Logviewer URL.
Navigate to the Deployments tab, save and open this URL.
This URL should show the Logviewer homepage.
### Part 2: Deploying the Modmail bot
From the [**New Project**](https://railway.app/new) page, create the project by selecting your **Modmail** repository, then select **Add variables**.
Choose your Modmail repository fork.
Click on Add variables. Alternatively, the following page can also be found within the project -> variables menu.
Click **New Variable.** We will be adding 5 variables in total, so repeat this step until you've added all 5 variables.
The Logviewer URL from your Notepad. Remember to add https:// in front!
https://web-production-1234.up.railway.app
OWNERS
Your Discord ID. If you have multiple owners, separate your IDs with a comma.
718827787302791100
GUILD_ID
The ID of the Discord server for your Modmail bot.
109483701365508619
Do you have a separate staff server?
If you manage a large server where you have a separate server for communication among your moderation team, Modmail supports directing threads into the staff server instead of your main (public) server.
Simply add an additional variable named **`MODMAIL_GUILD_ID`** and set the value to your staff server's ID.
Note: the **`GUILD_ID`** should always be your main server's ID (not staff server's).
If you haven't yet invited your Modmail bot to your staff server, see the [invite section](/installation#do-you-have-a-separate-staff-server).
Click on New Variable.
Once you've added the variable as per the table above, you should see 5 variables here.
### Complete the setup
Within 10 minutes of saving the Modmail bot variables, your Modmail bot should come online in your server. The default prefix for Modmail is **`?`**. You need to run **`?setup`** within your server to complete the setup. If you configured Modmail to use a separate staff server, you must run this command **in your staff server**. This will create a category for your Modmail threads and a Logs channel for an archive of all past threads.
Help! My bot hasn't started after 10 minutes.
This probably means you've failed to follow one or more steps. \[more info TODO]
### How to keep your bot running 24/7
You have 10 days to test Modmail without upgrading to the "Developer" plan. As mentioned in the [costs](#costs) section, Railway's Developer plan provides enough free monthly credits to run Modmail for **free** 24/7 everyday. However, you will need to provide your credit card details to upgrade your plan. More details can be found [here](https://docs.railway.app/reference/plans).
**Usage-based subscription**
Head over to the \*\*\*\* [**Billing Details**](https://railway.app/account/billing) page, click the **Unlock** button to unlock Developer plan. Then input your credit card details and hit **Subscribe to Developer Plan**.
{% hint style="warning" %}
Subscribing to the Developer plan under *usage based subscription* **may incur you unexpected charges**. This because Railway does not provide any safe-guards or monthly spending limits. Average Modmail and Logviewer usage should be well below the free threshold. However, if you run resource-intensive code via plugins or due to other means, you credit card may be billed.
If you want to guarantee that your credit card won't get charged for whatever reason, check out the [credit-based subscription model](#credit-based-subscription-alternative-subscription-model) instead. Alternatively, you can use a virtual credit card, such as [privacy.com](https://privacy.com/virtual-card), to verify for the Developer plan.
{% endhint %}
Click the Unlock button next to Unlock Developer Plan.
Fill in your credit card details then click Subscribe to Developer Plan.
Why was I charged $1.00 USD?
This should be a temporary charge to verify that your credit card works as expected. Railway explains this with:
A temporary hold of $1.00 USD will be placed on the card and then refunded immediately.
**Credit-based subscription (alternative subscription model)**
If you rather pay a one-time $5.00 USD non-refundable credit purchase instead of permanently linking your credit card, you can choose to use the credit-based subscription model. As long as you have a non-zero credit balance (which should be forever since the monthly operating cost for Modmail is $0.00), you will be continuously subscribed to the Developer plan.
Click the Unlock button next to Unlock Developer Plan.
Click Credit-based subscription at the bottom.
Fill in your credit card details, enter $5.00 as the amount (it's the minimum), then click Purchase Credits.
There you go! Your bot should now be able to run 24/7 without interruptions. Head over to the [**Usage**](https://railway.app/account/usage) page to make sure you won't be charged. Add up the estimated price for both your projects and verify that they're well below $5.00 USD.
Estimated Bill should be $0.00 and the sum of the Estimated should be well below $5.00.
How do I cancel my Developer plan subscription?
If you're subscribed under the [usage-based subscription](#usage-based-subscription) model, you can cancel your subscription by heading to the \*\*\*\* [**Billing Details**](https://railway.app/account/billing) page, click **Manage Subscription**, then click **Cancel plan**.
 
### Updating
Railway is configured to automatically update your Modmail bot and Logviewer whenever new updates become available.
How do I disable auto-updates?
You can disable auto-updates by heading to the settings page for **both** your Modmail and Logviewer projects. Under **Automatic Deployments**, click **Disable trigger**. 
### Next steps
Now that you've successfully set up Modmail, visit the [Getting Started](broken://pages/HL3nLvDTyLBFzn6x4QTZ) page to find information on using Modmail.
You can also join our [**Discord Server**](https://discord.gg/cnUpwrnpYb) to interact with our community or get support for Modmail.
# Heroku
Deploy Modmail on Heroku PaaS.
### What is Heroku?
Heroku is a container-based cloud Platform as a Service (PaaS). Developers use Heroku to deploy, manage, and scale modern apps.
### Requirements
* A credit card (for payment and verification).
* An email account.
* A [GitHub](https://github.com/signup) account.
* You have completed the initial steps: [invited your bot](/installation#create-a-discord-bot) and [created a MongoDB database](/installation#create-a-mongodb-database).
### Costs
Unfortunately, Heroku is no longer free-of-charge. You will need at least their Eco plan, which currently costs $5 USD per month. See their [pricing page](https://www.heroku.com/pricing) for more info and up-to-date prices.
If you are a higher-education student, you *may* be eligible for their [student offer](https://www.heroku.com/github-students), which grants you $13 USD of credits per month for 24 months—enough to host Modmail free for two years.
{% hint style="info" %}
The Basic Setup option below uses templates from our repository, while this is a simpler way to setup the bot, it is no longer recommended due to added complexities in the updating process.
It is recommended you use the complex setup, which allows for seamless autoupdate of your Modmail instance.
{% endhint %}
{% tabs %}
{% tab title="Complex Setup (recommended)" icon="shuttle-space" %}
{% stepper %}
{% step %}
## Fork our GitHub repositories
You will need to fork our repositories to deploy onto Heroku.
Make sure you're logged in to [GitHub](https://github.com/). You will need to fork **two** repositories.
First we fork the Modmail repository. Head over to , leave all the settings as default, and click **Create fork**.
Create a GitHub fork for the Modmail Repository.
Next do the same for the Logviewer repository by heading over to , leave all the settings as default, and click **Create fork**.
Create a GitHub fork for the Logviewer Repository.
Next, to keep your Modmail and Logviewer up to date, you will need to install the [Pull App](https://github.com/apps/pull). Simply head over to , click **Install**, choose **Only select repositories**, then select **both** the Modmail and Logviewer repositories that you forked in the previous step.
Select both the Modmail and Logviewer forks, then click Install.
Your GitHub should now be all set. Next step, [create a Heroku account](https://heroku.com) on their website to deploy your bot.
{% endstep %}
{% step %}
## Deploying the Log Viewer
Go to this link: `https://heroku.com/deploy?template=https://github.com/[YOUR GITHUB USERNAME HERE!!!]/logviewer`
*Fill in your Github username `[YOUR GITHUB USERNAME HERE!!!]` before pressing enter!*
**This is not the bot!**
Choose a name for your app and paste your Mongo URI in the field (from your notepad). After you click the `Deploy App` button, it will start creating the website.
After that's done configuring, click the `View` button. It will redirect you to the logviewer home screen. Copy the link in the address bar and paste it in Notepad.
{% endstep %}
{% step %}
## Deploying Modmail
**This is the second application you will be deploying - this is the actual bot.**
Go to this link: `https://heroku.com/deploy?template=https://github.com/[YOUR GITHUB USERNAME HERE!!!]/modmail`
*Fill in your Github username `[YOUR GITHUB USERNAME HERE!!!]` before pressing enter!*
**01.** Choose any name for your app. Note: this name doesn't matter at all.
**02.** Put your bot's token in the `TOKEN` field.
**03.** In the `DATABASE_TYPE` You may fillout: `mongodb`
**04.** Put the ID of your Server into the `GUILD_ID` field.
**05.** Put your own ID in the `OWNERS` field. If there are multiple owners, separate them by a comma.
**06.** Put your Mongo connection URI from the previous section in the `CONNECTION_URI` field.
**07.** Put the URL of your log viewer Heroku app (`https://yourlogviewerappname.herokuapp.com`) in the `LOG_URL` field.
**08** Click the `Deploy App` button and wait for it to finish.
**09.** Click `Manage App` and go into the `Resources` tab, where you need to turn on the worker by clicking the pencil icon next to it.
**10.** If you want, you can go over and check the application logs to see if everything is running smoothly. If any unexpected errors pop up, join our [Discord server](https://discord.gg/cnUpwrnpYb) and DM Modmail. Our support team will gladly assist with any issues.
**11.** Once the bot is online in your server, make sure to give it the required positions from [Installation](https://docs.modmail.dev/installation).
**12.** Run the `?setup` command and you are good to go!
{% endstep %}
{% step %}
## Updating
You can update Modmail on your Heroku account whenever changes are made to the repository. Link your GitHub Account to Heroku:
**One Time Update:** You then want to go to your modmail application in Heroku, connect your modmail fork via the `Deploy` tab and deploy the `master` branch.
**Automatic Updates:** You can turn on auto-deploy for the master branch if you don't want to go through the process of logging into Heroku and deploying the branch every time changes to the repo are made in the future.
{% endstep %}
{% endstepper %}
{% endtab %}
{% tab title="Basic Setup (not recommended)" icon="taxi" %}
{% stepper %}
{% step %}
## Deploying the Log Viewer
### **Click the button below to deploy the logviewer to Heroku!**
[](https://heroku.com/deploy?template=https://github.com/modmail-dev/logviewer)
**This is not the bot!**
You will need to deploy a separate log viewer application from [this repository](https://github.com/modmail-dev/logviewer). This Heroku application is separate from the bot; it's a simple website that will be used to display your thread logs.
Choose a name for your app and paste your Mongo URI (from your notepad). After you click the `Deploy App` button, it will start creating the website.
After that's done configuring, click the `View` button. It will redirect you to the logviewer home screen. Copy the link in the address bar and paste it in Notepad.
{% endstep %}
{% step %}
## Deploying Modmail
### **Click the button below to deploy the bot to heroku.**
**This is the second application you will be deploying - this is the actual bot.**
[](https://heroku.com/deploy?template=https://github.com/modmail-dev/modmail)
**1.** Choose any name for your app. Note: this name doesn't matter at all.
**2.** Put your bot's token in the `TOKEN` field.
**3.** In the `DATABASE_TYPE` You may fillout: `mongodb`
**4.** Put the ID of your Server into the `GUILD_ID` field.
**5.** Put your own ID in the `OWNERS` field. If there are multiple owners, separate them by a comma.
**6.** Put your Mongo connection URI from the previous section in the `CONNECTION_URI` field.
**7.** Put the URL of your log viewer Heroku app (`https://yourlogviewerappname.herokuapp.com`) in the `LOG_URL` field.
**8** Click the `Deploy App` button and wait for it to finish.
**9.** Click `Manage App` and go into the `Resources` tab, where you need to turn on the worker by clicking the pencil icon next to it.
**10.** If you want, you can go over and check the application logs to see if everything is running smoothly. If any unexpected errors pop up, join our [Discord server](https://discord.gg/cnUpwrnpYb) and DM Modmail. Our support team will gladly assist with any issues.
**11.** Once the bot is online in your server, make sure to give it the required positions from [Installation](https://docs.modmail.dev/installation).
**12.** Run the `?setup` command and you are good to go!
***
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}
# Free Logviewer Hosting
How to setup Lorenzo's Free Logviewer Hosting
[Lorenzo](https://lvh.lol), a long time contributor, supporter, and administrator in our community provides a free logviewer hosting service at this own expense to members of the Modmail community. Hosting using this service is facilitated through the Modmail project's official Discord server, which you can join [here](https://discord.gg/cnUpwrnpYb).
## Limitations
* You can only host three free logviewers with this service. Using secondary accounts, or other methods to bypass this limit may result in permanent restriction from the service. Please do not take abuse Lorenzo's selfless generosity. (He is providing this completely at his own expense.)
* If you wish to host additional logviewers with this service, DM our Modmail and you may be able to work out a deal at Lorenzo's discussion.
* Logviewers hosted can only be subdomains of the `logs.vodka` domain. (Ex: `[yourlogviewenamehere].logs.vodka`).
## Requirements
* Join our Discord Server
* Host your MongoDB connection URI using MongoDB Atlas (locally hosted databases are not supported).
* Set your MongoDB database Network Security to be accessible from anywhere. \*See an excerpt of our [installation guide](/installation) below if you did not do this during installation.)
Allow Database Access from Anywhere
Set IP Address to 0.0.0.0/0, then click Add Entry.
## Setup Steps
{% stepper %}
{% step %}
Have your MongoDB URI ready to go, you can use the same database account you used for your bot. Take a look at your `.env` file or enviornment variables if you don't have yours handy.
{% endstep %}
{% step %}
Choose the name you'd like for your logviewer, most people use a version of their server name.
{% endstep %}
{% step %}
Run this command
`/logviewer add [name] [mongouri]`
{% hint style="success" %}
It is really that simple, your Logviewer is now ready to go.
{% endhint %}
{% hint style="info" %}
It may take a few minutes before you are able to visit the newly deployed logviewer for a variety of reasons beyond Lorenzo, the Modmail team, or your control. If you can't access it right away wait 5-10 minutes, clear your browser cache, and try again.
While unusual, depending on the settings for your computer and network, it could take up to an hour, be patient and it should work itself out behind the scenes.
{% endhint %}
{% endstep %}
{% endstepper %}
## Viewing Your Logviewers
{% stepper %}
{% step %}
If you forget how many, or what logviewers you have created with the service, you can use this command to see what they are:
`/logviewer list`
{% endstep %}
{% endstepper %}
## Deleting a Logviewer
{% stepper %}
{% step %}
To delete your logviewer at any time, you can use this command:
`/logviewer delete [name]`
 
{% hint style="info" %}
If for any reason you want to rename your logviewer, the easiest way to do this would be to delete it, and then create it again with a new name while using the same MongoDB URI.
{% endhint %}
{% endstep %}
{% endstepper %}
Version History
## Initial Creation
Initial creation of docs page for using the Free Logviewer Hosting from Lorenzo.
# Modmail Hosting Panel
Deploy Modmail on Heroku PaaS.
The Modmail Hosting Panel, or Modmail Panel is a custom software stack that is designed for doing one thing, hosting Modmail. Because of this, it has an intuitive user interface, and a number of features that allow for a simple hosting experience. While similar in concept to systems like Pterodactyl, instead of trying to shoehorn a Discord bot into a game hosting platform, the platform starts Modmail first.
Currently, there are only two hosting options that use the Modmail Panel:
Modmail Team Hosting
We offer paid hosting solution for your Modmail bot. We will also fully manage your bot hosting for you, so you don't need to worry about upgrading or setting up your own host server. Refer to our [BMAC Hosting here](https://buymeacoffee.com/modmaildev/membership).
Prices start at $4 per month.
modmail.lvh.lol by Lorenzo
Run by a member of our community and team, this is the birthplace of the Modmail panel. \*The Modmail Team does not necessarily endorse this hosting provider.\*
Check it out at [modmail.lvh.lol](https://modmail.lvh.lol).
Prices start at $1.50 per month.
## Requirements
* Before setting up your bot on the Modmail Panel, you'll need to have all the elements we discuss in our [Installation Guide](/config-references):
* Discord Bot Token
* MongoDB Connection URI
* Server ID
* Logviewer URL
* Bot Owner ID(s)
## Setup
{% hint style="info" %}
For the purpose of this tutorial, the screenshots were taken on [modmail.lvh.lol](https://modmail.lvh.lol), however, if you are a Patreon or Buy Me a Coffee (BMAC) supporter, your process will be identical, but on our internal Modmail Panel. You can find the link in the Modmail Lounge server.
{% endhint %}
{% stepper %}
{% step %}
Login to the Modmail Panel using your Discord Account. For Buy Me a Coffee subscribers, you'll need to enter your email to link your BMAC membership to your Discord account in our system.
This is the Login page for the panel, press "Login with Discord" to get started.
{% endstep %}
{% step %}
Once you have logged in, and linked your BMAC account if necessary, you'll need to press **Create Instance** to open the creation screen.
This is the homepage of the panel once you have logged in. Press Create Instance to begin.
{% endstep %}
{% step %}
Next, give your instance a friendly name, this can be anything, for most people, it makes sense to use your server's name.
Also on this screen enter your:
* Token
* Server ID
* Any additional Owner IDs (yours will be autofilled)
* Log URI
* MongoDB Connection URI
If you still need to get this information reference our [Installation Guide](/config-references) for step by step instructions.
Once you have correctly entered these steps, press **Save Settings** and then confirm when prompted.
Enter the correct values into each of the fields shown, press the **Save Settings** box when completed.
After saving settings, you will receive a confirmation prompt to ensure you wish to change your bot's values, press **Ok**.
{% endstep %}
{% step %}
{% hint style="info" %}
For most users, it is recommended to leave the default selection of the **Master** branch with the **default** version.
If you have a reason to change this (such as needing experimental bug fixes in the Development branch), you can change this now, and then press the **Update Instance** button.
{% endhint %}
Once you have entered your bot's settings, press the green **Start** button to start the instance.
Press Start to boot up your instance for the first time.
Below your bot's settings, you can see the logs of your bot at any time. During setup it will simply display "(Waiting for bot to initialize...)". If there are issues during setup they will display here when you press Refresh.
{% endstep %}
{% step %}
Within 2-3 minutes your bot should go online in your server.
If not...
If it does not come online within 2-3 minutes, press the \*\*Refresh\*\* button on the logs to see what went wrong.
Below your bot's settings, you can see the logs of your bot at any time. During setup it will simply display "(Waiting for bot to initialize...)". If there are issues during setup they will display here when you press Refresh.
Your logs will look something similar to this once your setup is complete.
You can stop or restart your bot at any time using the **Stop** and **Restart** buttons at the top of the page.
{% hint style="success" %}
You have successfully deployed your Modmail bot using the Modmail Panel! You can now run `?setup` to get started. Take a look at our [usage guide](/usage-guide) if you need additional help.
*Note: as of the time of writing, on June 4th, 2026, the Modmail Panel does not support logviewer hosting, you'll need to handle this in other ways. For Patreon/BMAC supporters, contact the Modmail bot in the Modmail Lounge server for further assistance.*
{% endhint %}
{% endstep %}
{% endstepper %}
## Sharing Access to your Modmail Instance
If you have a server co-owner, or top team member who may need access to restart your bot, view its logs, or change configuration variables, you can share access to your Modmail instance directly in the Modmail Panel.
{% stepper %}
{% step %}
Login to the Modmail Panel for your host and navigate to the bot you wish to share.
Each bot has its own sharing settings, so if you'd like to share multiple bots, you'll need to do one at a time.
{% endstep %}
{% step %}
On the right under **Statistics** there is a field to enter the Discord User ID of the user you wish to share access with. For more details on obtaining someone's User ID, check our this [Discord Support Article](https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID).
You can share your Modmail instance with as many users as you would like, but, you'll need to add each User ID in one at a time.
Paste the user you wish to share access with in the field labeled User ID then press the + button.
{% endstep %}
{% step %}
{% hint style="success" %}
You have now successfully shared access to your Modmail instance to another user. They can now login to the Modmail Panel using their Discord account and access your bot. Their access will look like this:
{% endhint %}
{% endstep %}
{% endstepper %}
### Removing Access to a Shared Instance
If you have shared your bot with someone else, you can revoke their access at any time by pressing the **X** next to their username. See red box in the screenshot below:
If you have had a bot shared with you that you no longer wish to have access to, you can use the **Leave Instance** button as seen in the red box below:
Version History
## Initial Creation
Initial creation of docs page for using the Modmail Panel.
# Community Guides
Unofficial installation guides created by the community.
{% hint style="danger" %}
Community guides are not verified by the Modmail team, so use them at your own risks.
{% endhint %}
## [Replit Guide](https://gist.github.com/anondev-sudo/24978429b85b44348bcff5c0885afe82) by AnonDev
An online code execution environment that costs $7 USD per month. However, hosting on Replit is often unstable, and thus not recommended. For the up-to-date pricing info check out their [pricing](https://replit.com/pricing) page.
{% hint style="warning" %}
Replit is on the Modmail Team's unrecommended hosts list. See more details on the [unrecommended hosts page](/choose-host/unrecommended-hosts)
**The Modmail team does not provide any support of any kind to anyone hosting with Repl.it.**
{% endhint %}
## [Oracle Guide](https://docs.lidistat67.eu/) by lidistat67
Oracle Cloud Compute is an Infrastructure as a Service (IaaS) platform. Unlike Railway and Heroku, Oracle gives you access to a VPS where you can have a more direct control of your instance. Oracle is a reputable company known for owning products such as Java, VirtualBox, MySQL, etc. Oracle Cloud offers 3,000 OCPU hours and 18,000 GB hours per month. This is equivalent to 24 GB of RAM and 4 OCPUs. TL;DR, Oracle offers powerful instances for free! Oracle requires a credit card for verification but will never charge you as long as you are on their free plan. The setup is similar to self-hosting Modmail as Oracle offers a VPS.
## [Pterodactyl](https://martinbndr.gitbook.io/modmail-hosting-on-pterodactyl/) Guide by martinbndr
Pterodactyl is a hosting self hostable platform that originally allows to host gameservers but it can also host other applications like modmail. Some hosting provider providing you a free plan in order to application via this panel.
{% hint style="warning" %}
Pterodactyl Panel based hosts are on the Modmail Team's use-caution hosting providers list. For more information, please view [the additional considerations page](https://github.com/kyb3rr/modmail-docs/blob/main/choose-host/choose-host1.md) in our [choosing a host guide](/choose-host).
{% endhint %}
# Updating
Guide on how to update the Modmail bot.
You can run the `?update` command on your bot manually, replacing `?` with your bot prefix.
If for some reason your update command isn't working correctly, you can update your bot by going into your Modmail folder and pulling the latest changes from GitHub with the steps below.
First, determine whether you have the official Modmail repository cloned or a fork by observing the output of the command below:
```
cat .git/config
```
If the output shows this exact URL as shown below,
```
[remote "origin"]
url = https://github.com/modmail-dev/modmail.git
```
you can go ahead and run the command below to pull in the latest changes:
```bash
git pull
```
Else, it means that your repository is a fork and must update (aka sync) it independently. If your repository is hosted on GitHub, click on the button on your repo's GitHub URL as highlighted below:
Run the `git pull` command above locally after syncing your fork.
And then, be sure to restart your bot to apply the update.
## Breaking Changes and Update Compatibility
For the most part, it is not necessary to worry about updating from one version to the other. However, before updating, take a look at the most recent changelog entry to see if there is a **"Breaking"** note. If you are updating from a very old version, start at the version you are currently on, and scroll up to the current version, and check to see if there are any **Breaking** notes. If there are none, you can update without issue. (Remember to backup your files.)
If there is a **Breaking** entry in the changelog, read to see what steps are required to maintain functionality. If you need assistance, contact the Modmail Team in our official [support server *preferred*](https://discord.gg/cnUpwrnpYb) or on [GitHub](https://github.com/modmail-dev)
# Usage
How to use modmail
After initial setup is done, you can use modmail by using the in text commands. These use the prefix you set with the `prefix` command. The default prefix is `?`. Users can DM the bot to start a thread. Any users or roles set with the `?permissions` command can then see the thread in the server and reply to it.
## Replying
To reply to a thread, use the `?reply` command inside the thread you wish to reply in. This will send a message to the thread. Image attachments and stickers are supported and will also be sent to the user. Without command, any message sent in the thread will be seen as an internal message. This will not be visible to the user, but will still be logged to be viewed later in logviewer. If rather you want to send a message to the user without command, set the config variable `reply_without_command` to `true` using the `?config` command
## Closing
When communications with a user have come to a conclusion, the thread can be closed in a multitude of ways. The recommended way is using the `?close` command. By default, this will close the thread on invoking the command. A message will be sent to the user containing the value of the `thread_close_response` config variable. This can be changed using the `?config` command. A one time override can be given by adding text to the `close` command. E.g. `?close Thanks for contacting us!` will send the message `Thanks for contacting us!` to the user instead of the default message. A time can also be provided to the close command. This will result in the close being scheduled and will automatically close the thread after the given time has expired. Multiple formats for time are accepted, like `2m30s` or `5 hours`. A response message can also be added to a timed close. When either a staff member, or the user themselves, replies to the thread after the close has been scheduled, the close will be cancelled.
## Help command
To assist with command usage, every command has a description. This description can be retrieved by using the `?help` command followed by the name of the command. E.g. `?help close` will show the description of the `?close` command. Most command descriptions also contain examples of how to use the command. The `?help` command can also be used without a command name to show a list of all commands.
## Snippets
The modmail bot has a snippet system to make frequent responses easier. Snippets can be created using the `?snippet` command. This will create a snippet with the given name and content. The snippet can then be used by using the snippet name as a command. E.g. `?snippetname` will send the content of the snippet named `?snippetname` to the thread. Using the `?snippets` command will list all currently defined snippets. Using `?snippet (snippet name)` will show the content of the snippet without sending it to the thread.
## Logging
All messages sent in a thread, including internal notes, are logged to the bot's database. When a thread is closed, a message will be sent by the bot in the logs channel containing a link to the log. This link can be used to view the log in the logviewer. In a thread, the `loglink` command can be used to retrieve the loglink before it is closed. This allows the user to view the log before it appears in the logs channel if required. Logviewer is read only, and cannot be used to edit or delete messages.
# Plugins
Plugins can add additional functionality into the modmail bot. You can view a list of approved plugins via the `?plugins registry` command or take a look at the [`plugins/registry.json`](https://github.com/modmail-dev/modmail/blob/master/plugins/registry.json).
## Guidelines
To get approved and officially verified, you need to ensure you follow these guidelines:
* Supporting Python 3.10 (and above).
* No malicious intent.
* The plugin cannot be a feature pending to be added into [Modmail](https://github.com/modmail-dev/modmail/issues). You can submit a PR to add it to the core Modmail.
* Core Modmail still needs to 100% function.
* Cog name cannot be the same as any current class (`Core`, `Modmail`).
* It cannot have the same name as another approved plugin.
## Creating Plugins
We use [discord.py](https://discordpy.readthedocs.io/en/stable/) for the bot and plugins take the form of [Cogs](https://discordpy.readthedocs.io/en/stable/ext/commands/cogs.html).
Short example:
```py
from discord.ext import commands
class Hello(commands.Cog):
def __init__(self, bot):
self.bot = bot
@commands.Cog.listener()
async def on_message(self, message):
print(message.content)
@commands.command()
async def say(self, ctx, *, message):
await ctx.send(message)
async def setup(bot):
await bot.add_cog(Hello(bot))
```
### Folder Structure
Your plugin has to be uploaded on Github on a **public repository.** (Note: private repositories are supported, but they require extra setup, see [Private Plugins](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token)). The repository folder structure has to be as follows:
```yaml
root:
plugin_name:
..
plugin_name.py
requirements.txt [optional]
plugin_name:
..
plugin_name.py
requirements.txt [optional]
```
The plugin will be loaded with something similar to
```py
await bot.load_extension('username.plugin_name.plugin_name')
```
To install a plugin that is not in the official registry, type:
```
?plugin add githubusername/plugin_repo/plugin_name[@branch]
```
An example of a plugin can be seen at [`fourjr/modmail-plugins`](https://github.com/fourjr/modmail-plugins) or any of the plugins in our [registry](https://github.com/modmail-dev/modmail/blob/master/plugins/registry.json).
#### Branch parameter
The branch parameter is **optional** (default to `master`) and can be used to test in-development/unstable plugins with a development branch.
Users will always be updated to the latest version. Thus, if there is a broken plugin on the latest version, users would not be able to use the plugin.
#### @local (For Developers)
To make it easier to develop a plugin, there's a folder named `@local` in the plugins folder. You can directly put a folder for each plugin in it.
Using the example cog above, the load command would be
```
?plugin load @local/hello
```
{% hint style="info" %}
You can also use this as a way to have a private plugin installed on your bot if you host locally or on a VPS, and do not intend to update your plugin frequently. If you plan on even semi-frequent updates, you should use the private plugins process listed below.
{% endhint %}
#### Best Practices
1. Create a development branch
2. Push to it until you are confident that your code is stable
3. Merge it into `master` using pull requests or `git merge -v dev --squash`
4. Update your plugin!
### Private Plugins
* Obtain a [Github Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `repo` scope
* Include `GITHUB_TOKEN` as a config variable (or in .env) with the token as the value.
* Upload your code to a private Github repository.
* Install just like a normal public plugin.
### Database Interfacing
Do **not** interact with `bot.api` directly. Fetch a partition and use it:
```python
def __init__(self, bot): # in the class init
self.coll = bot.api.get_plugin_partition(self)
```
`self.coll` is a [motor.motor\_asyncio.AsyncIOMotorCollection](https://motor.readthedocs.io/en/stable/api-asyncio/asyncio_motor_collection.html)
### Additional PIP requirements
Create a [`requirements.txt` file](https://pip.pypa.io/en/stable/user_guide/#requirements-files) in the plugin folder. Packages listed here would be installed via something similar to the following command:
```
python3 -m pip install -r requirements.txt --user -q -q
```
### Exposed Events
The bot dispatches custom events to aid plugin developers to extend Modmail functionality.
Currently, we have these custom coroutines:
* `Bot.format_channel_name(bot, author, exclude_channel=None, force_null=False)` can be overwritten for custom behaviour.
* `on_plugins_ready()` which is dispatched when all the plugins are fully loaded and ready to be used.
* `on_thread_initiate(thread, creator, category, initial_message)` which is dispatched at the beginning of setup process. It is recommended to use the other events instead.
* `on_thread_create(thread)` which is dispatched when the thread is registered as a thread by Modmail (i.e., when channel topic is edited).
* `on_thread_ready(thread, creator, category, initial_message)` which is dispatched when a thread channel is created and the `genesis_message` (info embed) is sent. It is recommended to use this event.
* `on_thread_close(thread, closer, silent, delete_channel, message, scheduled)` which is dispatched when a thread is closed, after channel deletion.
* `on_thread_reply(thread, from_mod, message, anonymous, plain)` which is dispatched upon any reply.
e.g.
```py
@commands.Cog.listener()
async def on_thread_ready(self, thread, creator, category, initial_message):
msg = thread.genesis_message
... # do stuff
```
### Approval request
Create a [Pull Request](https://github.com/modmail-dev/modmail/pulls) adding your plugin into [`plugins/registry.json`](https://github.com/modmail-dev/modmail/blob/master/plugins/registry.json) and we will take a look at it.
# Configuration
Configuring and customizing modmail.
Modmail offers an assort of customizations to make your Modmail bot unique to your server. Most customizations can be set with `?config`, but some has its own special command, such as `?activity`. You may find all of the personalizable tweaks available for Modmail below:
{% hint style="info" %}
All examples presume your prefix is \`?\`.
{% endhint %}
{% hint style="warning" %}
Things covered in brackets are optional: \`\[]\` Things covered in angled brackets are required: \`<>\`
{% endhint %}
**Quick Navigation:**
**Moderation:**
* [Prefix](/usage-guide/configuration)
* [Mention](https://github.com/kyb3rr/modmail-docs/blob/main/usage-guide/usage-guide/configuration/README.md#mention-mention)
## Moderation Configurations
### Account Age ( account\_age )
***Default:*** No Age Threshold
Set an amount of time a users account has to be created in order to open a ticket.
***Example:***
* `?config set account_age P12DT3H` (stands for 12 days and 3 hours in [ISO-8601 Duration Format](https://en.wikipedia.org/wiki/ISO_8601#Durations))
* `?config set account_age 3 days and 5 hours` (accepted readable time)
***Note(s):***
* To remove this restriction, do ?config del account\_age.
* See also: `guild_age`.
### Alert on Mention ( alert\_on\_mention )
***Default:*** No
Mentions all mods (mention) in mention channel when bot is mentioned
***Example:***
* `?config set alert_on_mention yes`
***Notes:***
* See also: `mention`, `mention_channel_id`
### Prefix ( prefix )
The prefix of the bot
***Default:*** `?`
***Example:***
* `?config set prefix !`
* `?prefix !`
This both result in commands now prefixed with !, for example:
{% hint style="success" %}
!about
{% endhint %}
***Notes:***
* If you forgot the bot prefix, Modmail will always respond to its mention (ping).
* To reset the prefix back to default: `?config del prefix`
### Guild Age ( guild\_age )
The join date of the recipient user into this server must be greater than the number of days, hours, minutes or any time-interval specified by this configuration.
***Default:*** No age threshold
***Example:***
* `?config set guild_age P12DT3H` (stands for 12 days and 3 hours in [ISO-8601 Duration Format](https://en.wikipedia.org/wiki/ISO_8601#Durations))
* `?config set guild_age 3 days and 5 hours` (accepted readable time)
***Notes:***
* To remove this restriction, do `{prefix}config del guild_age`.
* See also: `account_age`.
### Reply Without Command ( reply\_without\_command )
***Default:*** Disabled
Setting this configuration will make all non-command messages sent in the thread channel to be forwarded to the recipient without the need of `?reply`.
***Example:***
* `?config set reply_without_command yes`
* `?config set reply_without_command no`
***Notes:***
* See also: `anon_reply_without_command`, `plain_reply_without_command`.
### Show Timestamps ( show\_timestamp )
***Default:*** Yes
Shows timestamps on thread embeds
***Example:***
* `?config set show_timestamp no`
### Silent Alert On Commands ( silent\_alert\_on\_mention )
Send a message in the mention channel without mentioning all mods (mention).
***Default:*** No
***Example:***
* `?config set alert_on_mention yes`
***Notes:*** This has no effect unless `alert_on_mention` is set to yes. See also: `mention`, `mention_channel_id`
### Update Channel ID ( update\_channel\_id )
This is the channel where update notifications are sent to.
***Default:*** Log Channel (normally `#bot-logs`)
***Example:***
* `?config set update_channel_id 9234932582312` (9234932582312 is the channel ID)\`
***Notes:***
* This has no effect unless `disable_autoupdates` is set to no and `update_notifications` is set to yes.
* See also: `log_channel_id`
### Update Notifications ( update\_notifications )
This is the channel where update notifications are sent to.
***Default:*** Yes
***Example:***
* `?config set update_notifications no`
***Notes:***
* This has no effect unless `disable_autoupdates` is set to no.
* See also: `update_channel_id`
### Fallback Category ID ( fallback\_category\_id )
This is the category that will hold the threads when the main category is full.\n\nTo change the Fallback category, you will need to find the [category’s ID](https://support.discordapp.com/hc/en-us/articles/206346498).
***Default:*** `Fallback Modmail` (created when the main category is full)
***Example:***
* `?config set fallback_category_id 9234932582312` (`9234932582312` is the category ID)
***Notes:***
* If the Fallback category ended up being non-existent/invalid, Modmail will create a new one. To fix this, set `fallback_category_id` to a valid category.
* See also: `main_category_id`.
### Log Channel ID ( log\_channel\_id )
This is the channel where all log messages will be sent (ie. thread close message, update message, etc.).\n\nTo change the log channel, you will need to find the [channel’s ID](https://support.discordapp.com/hc/en-us/articles/206346498). The channel doesn’t necessary have to be under the `main_category`.
***Default:*** `#bot-logs` (created with `?setup`)
***Example:***
* `?config set log_channel_id 9234932582312` (9234932582312 is the channel ID)
***Notes:***
* If the Modmail logging channel ended up being non-existent/invalid, no logs will be sent.
### Main Category ID ( main\_category\_id )
This is the category where all new threads will be created.\n\nTo change the Modmail category, you will need to find the [category’s ID](https://support.discordapp.com/hc/en-us/articles/206346498).
***Default:*** `Modmail` (created with `?setup`)
***Example:***
* `?config set main_category_id 9234932582312` (`9234932582312` is the category ID)\`
***Notes:***
* If the Modmail category ended up being non-existent/invalid, Modmail will break. To fix this, run `?setup` again or set `main_category_id` to a valid category.
* When the Modmail category is full, new channels will be created in the fallback category.
* See also: `fallback_category_id`
### Mod Typing ( mod\_typing )
When this is set to `yes`, whenever a moderator starts to type in the thread channel, the recipient user will see "{bot.user.display\_name} is typing…" in their DM channel.
***Default:*** Disabled
***Example:***
* `?config set mod_typing yes`
* `?config set mod_typing no`
***Notes:***
* See also: `mod_typing`
### User Typing ( user\_typing )
When this is set to `yes`, whenever the recipient user starts to type in their DM channel, the moderator will see “{bot.user.display\_name} is typing…” in the thread channel.
***Default:*** Enabled
***Example:***
* `?config set user_typing yes`
* `?config set user_typing no`
***Notes:***
* See also: `mod_typing`.
### Twitch URL ( twitch\_url )
This channel dictates the linked Twitch channel when the activity is set to "Streaming".
***Default:*** `https://www.twitch.tv/discordmodmail/`
***Example:***
* `?config set twitch_url https://www.twitch.tv/yourchannelname/`
***Notes:***
* This has no effect when the activity is not set to "Streaming".
* See also: `?help activity`
### Close On Leave ( close\_on\_leave )
Closes a modmail thread upon user leave automatically
***Default:*** No
***Example:***
* `?config set close_on_leave yes`
***Notes:***
* See also: `close_on_leave_reason`.
### Confirm Thread Creation ( confirm\_thread\_creation )
Ensure users confirm that they want to create a new thread
***Default:*** No
***Example:***
* `?config set confirm_thread_creation yes`
***Notes:***
* See also: `confirm_thread_creation_title`, `confirm_thread_response`, `confirm_thread_creation_accept`, `confirm_thread_creation_deny`
### Mention ( mention )
This is the message above user information for when a new thread is created in the channel.
***Default:*** `@here`
***Example:***
* `?config set mention Yo~ Here's a new thread for ya!`
* `?mention Yo~ Here's a new thread for ya!`
***Notes:***
* To disable mention, use command `?mention disable`.
* See also: `?help mention`.
### Require Close Reason ( require\_close\_reason )
Require a reason to close threads.
***Default:*** No
***Example:***
* `?config set require_close_reason yes`
### Thread Auto Close ( thread\_auto\_close )
Setting this configuration will close threads automatically after the number of days, hours, minutes or any time-interval specified by this configuration.
***Default:*** Never
***Example:***
* `?config set thread_auto_close P12DT3H` (stands for 12 days and 3 hours in [ISO-8601 Duration Format](https://en.wikipedia.org/wiki/ISO_8601#Durations))
* `?config set thread_auto_close 3 days and 5 hours` (accepted readable time)
***Notes:***
* To disable auto close, do `?config del thread_auto_close`.
* To prevent a thread from auto-closing, do `?close cancel`.
* See also: `thread_auto_close_silently`, `thread_auto_close_response`.
### Thread Cooldown ( thread\_cooldown )
Specify the time required for the recipient to wait before allowed to create a new thread.
***Default:*** Never
***Example:***
* `?config set thread_cooldown P12DT3H` (stands for 12 days and 3 hours in [ISO-8601 Duration Format](https://en.wikipedia.org/wiki/ISO_8601#Durations))
* `?config set thread_cooldown 3 days and 5 hours` (accepted readable time)
***Notes:***
* To disable thread cooldown, do `?config del thread_cooldown`.
### Thread Move Notify ( thread\_move\_notify )
Notify the recipient if the thread was moved.
***Default:*** No
***Example:***
* `?config set thread_move_notify yes`
* `?config set thread_move_notify no`
***Notes:***
* See also: `thread_move_title`, `thread_move_response`, `thread_move_notify_mods`.
### Thread Move Notify Mods ( thread\_move\_notify\_mods )
Notify mods again after the thread is moved
***Default:*** No
***Example:***
* `?config set thread_move_notify_mods yes`
* `?config set thread_move_notify_mods no`
***Notes:***
* See also: `thread_move_title`, `thread_move_response`, `thread_move_notify`.
### Use Regex Autotrigger ( use\_regex\_autotrigger )
Whether to use regex to compare in autotriggers.
***Default:*** No
***Example:***
* `?config set use_regex_autotrigger yes`
***Notes:***
{% hint style="danger" %}
This is meant for advanced user that understand regular expressions.
{% endhint %}
* You can test it out with on `PCRE (Server)` mode
* See command: `autotrigger`
### Plain Reply Without Command ( plain\_reply\_without\_command )
Setting this configuration will make all non-command messages sent in the thread channel to be forwarded to the recipient in a plain form without the need of `?reply`.
***Default:*** Disabled
***Example:***
* `?config set plain_reply_without_command yes`
* `?config set plain_reply_without_command no`
***Notes:***
* See also: `reply_without_command`, `anon_reply_without_command`.
### Anonymous Snippets ( anonymous\_snippets )
Sends snippets anonymously.
***Default:*** No
***Example:***
* `?config set anonymous_snippets yes`
***Notes:***
* See also: `anon_avatar_url`, `anon_tag`, `plain_snippets`.
## Appearance Configurations
### Blocked Emoji ( blocked\_emoji )
This is the emoji added to the message when when a Modmail action is invoked unsuccessfully (ie. DM Modmail when blocked, failed to reply, etc.).
***Default:*** 🚫
***Example:***
* `?config set blocked_emoji 🙅`
***Notes:***
* You can disable `blocked_emoji` with `?config set blocked_emoji disable`.
* Custom/animated emojis are also supported, however, the emoji must be added to the server.
* See also: `sent_emoji`.
### Close Emoji ( close\_emoji )
This is the emoji the recipient can click to close a thread themselves. The emoji is automatically added to the `thread_creation_response` embed.
***Default:*** 🔒
***Example:***
* `?config set close_emoji 👍`
***Notes:***
* This will only have an effect when `recipient_thread_close` is enabled.
* See also: `recipient_thread_close`.
### Confirm Thread Creation Accept ( confirm\_thread\_creation\_accept )
Emoji to accept thread creation
***Default:*** \u2705
***Example:***
* `?config set confirm_thread_creation_accept \u2611`
***Notes:***
* This has no effect unless `confirm_thread_creation` is set
* See also: `confirm_thread_creation`, `confirm_thread_creation_title`, `confirm_thread_response`, `confirm_thread_creation_deny`
### Confirm Thread Creation Deny ( confirm\_thread\_creation\_deny )
Emoji to cancel thread creation
***Default:*** \uD83D\uDEAB
***Example:***
* `?config set confirm_thread_creation_deny \u26D4`
***Notes:***
* This has no effect unless `confirm_thread_creation` is set
* See also: `confirm_thread_creation`, `confirm_thread_creation_title`, `confirm_thread_response`, `confirm_thread_creation_accept`
### Error Color ( error\_color )
This is the color for Modmail when anything goes wrong, unsuccessful commands, or a stern warning.
***Default:*** Discord Red [#E74C3C](https://placehold.it/100/e74c3c?text=+)
***Example:***
* `?config set error_color ocean blue`
* `?config set error_color ff1242`
* `?config set error_color #ff1242`
* `?config set error_color fa1`
***Notes:***
* Available color names can be found on [Color Options](https://docs.modmail.dev/old-docs/color-names).
* See also: `main_color`, `mod_color`, `recipient_color`.
### Main Color ( main\_color )
This is the main color for Modmail (help/about/ping embed messages, subscribe, move, etc.).
***Default:*** Discord Blurple [#7289DA](https://placehold.it/100/7289da?text=+)
***Example:***
* `?config set main_color olive green`
* `?config set main_color 12de3a`
* `?config set main_color #12de3a`
* `?config set main_color fff`
***Notes:***
* Available color names can be found on [Color Options](https://docs.modmail.dev/old-docs/color-names).
* See also: `error_color`, `mod_color`, `recipient_color`.
### Mod Color ( mod\_color )
This is the color of the messages sent by the moderators, this applies to messages within in the thread channel and the DM thread messages received by the recipient.
***Default:*** Discord Green [#2ECC71](https://placehold.it/100/2ecc71?text=+)
***Example:***
* `?config set mod_color dark beige`
* `?config set mod_color cb7723`
* `?config set mod_color #cb7723`
* `?config set mod_color c4k`
***Notes:***
* Available color names can be found on [Color Options](https://docs.modmail.dev/old-docs/color-names).
* See also: `recipient_color`, `main_color`, `error_color`.
### React To Contact Emoji ( react\_to\_contact\_emoji )
An emoji which is tracked in `react_to_contact_message`
***Default:*** \u2705
***Example:***
* `?config set react_to_contact_emoji \u2705`
***Notes:***
* See also: `react_to_contact_message \u2705`
### Recipient Color ( recipient\_color )
This is the color of the messages sent by the recipient, this applies to messages received in the thread channel.
***Default:*** "Discord Gold [#F1C40F](https://placehold.it/100/f1c40f?text=+)
***Example:***
* `?config set recipient_color dark beige`
* `?config set recipient_color cb7723`
* `?config set recipient_color #cb7723`
* `?config set recipient_color c4k`
***Notes:***
* Available color names can be found on [Color Options](https://docs.modmail.dev/old-docs/color-names).
* See also: `mod_color`, `main_color`, `error_color`.
### Sent Emoji ( sent\_emoji )
This is the emoji added to the message when when a Modmail action is invoked successfully (ie. DM Modmail, edit message, etc.).
***Default:*** ✅
***Example:***
* `?config set sent_emoji ✨`
***Notes:***
* You can disable `sent_emoji` with `?config set sent_emoji disable`.
* Custom/animated emojis are also supported, however, the emoji must be added to the server.
* See also: `blocked_emoji`.
### Show Log URL Button ( show\_log\_url\_button )
Shows the button to open the Log URL.
***Default:*** No
***Example:***
* `?config set show_log_url_button yes`
## Thread Appearance
### Use Random Channel Name ( use\_random\_channel\_name )
When this is set to `yes`, new thread channels will be named with random characters tied to their user ID.
***Default:*** No
***Example:***
* `?config set use_random_channel_name yes`
* `?config set use_random_channel_name no`
***Notes:***
{% hint style="warning" %}
This config is suitable for servers in Server Discovery to comply with channel name restrictions.
{% endhint %}
{% hint style="danger" %}
This cannot be applied with \`use\_timestamp\_channel\_name\`, \`use\_nickname\_channel\_name\`, or \`use\_user\_id\_channel\_name\`.
{% endhint %}
* See also: `use_timestamp_channel_name`, `use_user_id_channel_name`, `use_nickname_channel_name`.
### Use Timestamp Channel Name ( use\_timestamp\_channel\_name )
When this is set to `yes`, new thread channels will be named with the recipient's account creation date instead of the recipient's name.
***Default:*** No
***Example:***
* `?config set use_timestamp_channel_name yes`
* `?config set use_timestamp_channel_name no`
***Notes:***
{% hint style="warning" %}
This config is \*\*NOT\*\* suitable for servers in Server Discovery to comply with channel name restrictions.
{% endhint %}
{% hint style="danger" %}
This cannot be applied with \`use\_user\_id\_channel\_name\`, \`use\_random\_channel\_name\` or \`use\_nickname\_channel\_name\`.
{% endhint %}
* See also: `use_user_id_channel_name`, `use_nickname_channel_name`, `use_random_channel_name`.
### Use User ID Channel Name ( use\_user\_id\_channel\_name )
When this is set to `yes`, new thread channels will be named with the recipient's ID instead of the recipient's name.
***Default:*** No
***Example:***
* `?config set use_user_id_channel_name yes`
* `?config set use_user_id_channel_name no`
***Notes:***
{% hint style="warning" %}
This config is suitable for servers in Server Discovery to comply with channel name restrictions.
{% endhint %}
{% hint style="danger" %}
This cannot be applied with \`use\_timestamp\_channel\_name\`, \`use\_random\_channel\_name\` or \`use\_nickname\_channel\_name\`.
{% endhint %}
* See also: `use_timestamp_channel_name`, `use_nickname_channel_name`, `use_random_channel_name`.
### Use Nickname Channel Name ( use\_nickname\_channel\_name )
When this is set to `yes`, new thread channels will be named with the recipient's nickname instead of the recipient's name.
***Default:***
***Example:***
* `?config set use_nickname_channel_name yes`
* `?config set use_nickname_channel_name no`
***Notes:***
{% hint style="warning" %}
This config is suitable for servers in Server Discovery to comply with channel name restrictions.
{% endhint %}
{% hint style="danger" %}
This cannot be applied with \`use\_timestamp\_channel\_name\`, \`use\_random\_channel\_name\` or \`use\_user\_id\_channel\_name\`.
{% endhint %}
* See also: `use_timestamp_channel_name`, `use_user_id_channel_name`, `use_random_channel_name`.
### Use Hoisted Top Role ( use\_hoisted\_top\_role )
Controls if only hoisted roles are evaluated when finding top role.
***Default:*** Yes
***Example:***
* `?config set use_hoisted_top_role yes`
* `?config set use_hoisted_top_role no`
***Notes:***
* Top role is displayed in embeds when replying or adding/removing users to a thread in the case mod\_tag and anon\_username are not set.
* If this configuration is enabled, only roles that are hoisted (displayed seperately in member list) will be used. If a user has no hoisted roles, it will return 'None'.
* If you would like to display the top role of a user regardless of if it's hoisted or not, disable `use_hoisted_top_role`.
### Thread Show Account Age ( thread\_show\_account\_age )
Shows account age on first message sent in thread channels to mods
***Default:*** Yes
***Example:***
* `?config set thread_show_account_age no`
***Notes:***
* See also: `thread_show_roles`, `thread_show_join_age`
### Thread Show Join Age ( thread\_show\_join\_age )
Shows join age on first message sent in thread channels to mods
***Default:*** Yes
***Example:***
* `?configconfig set thread_show_join_age no`
***Notes:***
* See also: `thread_show_account_age`, `thread_show_roles`.
### Thread Show Roles ( thread\_show\_roles )
Shows roles on first message sent in thread channels to mods
***Default:*** Yes
***Example:***
* `?config set thread_show_account_age no`
***Notes:***
* See also: `thread_show_roles`, `thread_show_join_age`.
### Mod Tag ( mod\_tag )
This is the name tag in the “footer” section of the embeds sent by moderators in the recipient DM and thread channel.
***Default:*** The moderator's highest role
***Example:***
* `?config set mod_tag Moderator`
***Notes:***
{% hint style="warning" %}
When the message is sent anonymously, \`anon\_tag\` is used instead.
{% endhint %}
* See also: `anon_tag`.
### Anon Tag ( anon\_tag )
This is the name tag in the “footer” section of the embeds sent by anonymous moderators in the recipient DM.
***Default:*** "Response"
***Example:***
* `?config set anon_tag Support Agent`
***Notes:***
* See also: `anon_avatar_url`, `anon_username`, `mod_tag`.
### Anon Avatar URL ( anon\_avatar\_url )
This is the avatar of the embeds sent by anonymous moderators in the recipient DM.
***Default:*** Server avatar
***Example:***
* `?config set anon_avatar_url https://path.to/your/avatar.png` (you will need to upload the avatar to somewhere)
***Notes:***
* See also: `anon_username`, `anon_tag`.
### Anon Username ( anon\_username )
This is the name in the “author” section of the embeds sent by anonymous moderators in the recipient DM.
***Default:*** Fallback on `mod_tag`
***Example:***
* `?config set anon_username Incognito Mod`
***Notes:***
* See also: `anon_avatar_url`, `anon_tag`.
### Transfer Reactions ( transfer\_reactions )
Transfer users reactions to mods and vice versa *(If someone reacts to a thread message the other party will see it.)*
***Default:*** Yes
***Example:***
* `?config set transfer_reactions no`
## Thread Responses
### Close On Leave Reason ( close\_on\_leave\_reason )
Reason for closing the thread once member leaves
***Default:*** The recipient has left the server.
***Example:***
* `?config set close_on_leave_reason Member left`
***Notes:***
* This has no effect unless `close_on_leave` is set.
* See also: `close_on_leave`.
### Confirm Thread Creation Title ( confirm\_thread\_creation\_title )
Title for the embed message sent to users to confirm a thread creation
***Default:*** Confirm thread creation
***Example:***
* `?config set confirm_thread_creation_title Are you sure you want to create a new thread?`
***Notes:***
* See also: `confirm_thread_creation`, `confirm_thread_response`, `confirm_thread_creation_accept`, `confirm_thread_creation_deny`
### Confirm Thread Response ( confirm\_thread\_response )
Description for the embed message sent to users to confirm a thread creation
***Default:*** React to confirm thread creation which will directly contact the moderators
***Example:***
* `?config set confirm_thread_response React to confirm`
***Notes:***
* See also: `confirm_thread_creation`, `confirm_thread_creation_title`, `confirm_thread_creation_accept`, `confirm_thread_creation_deny`
### Cooldown Thread Response ( cooldown\_thread\_response )
The description of the message embed when the user has a cooldown before creating a new thread.
***Default:*** Your cooldown ends {delta}. Try contacting me then.
{% hint style="info" %}
\`{delta}\` will be replaced with whatever time you gave it.
{% endhint %}
***Example:***
* `?config set cooldown_thread_response Be patient! You are on cooldown, wait {delta} more.`
***Notes:***
* "Only has an effect when `thread_cooldown` is set
* Must have a {delta} included which will be replaced with the duration of time.
* See also: `cooldown_thread_title`.
### Cooldown Thread Title ( cooldown\_thread\_title )
The title of the message embed when the user has a cooldown before creating a new thread.
***Default:*** Message not sent!
***Example:***
* `?config set cooldown_thread_title Error`
***Notes:***
* Only has an effect when `thread_cooldown` is set
* See also: `cooldown_thread_response`.
### Disabled Current Thread Footer ( disabled\_current\_thread\_footer )
The footer of the message embed when Modmail DM is disabled and user DMs Modmail from existing thread.
***Default:*** Please try again later...
***Example:***
* `?config set disabled_current_thread_footer Message back!`
***Notes:***
* Only has an effect when `{prefix}disable all` is set.
* See also: `disabled_current_thread_title`, `disabled_current_thread_response`, `disabled_new_thread_footer`.
### Disabled Current Thread Response ( disabled\_current\_thread\_response )
The body of the message embed when Modmail DM is disabled and user DMs Modmail from existing thread.
***Default:*** We are not accepting any messages.
***Example:***
* `?config set disabled_current_thread_response On break right now.`
***Notes:***
* Only has an effect when `{prefix}disable all` is set.
* See also: `disabled_current_thread_title`, `disabled_current_thread_footer`, `disabled_new_thread_response`.
### Disabled Current Thread Title ( disabled\_current\_thread\_title )
The title of the message embed when Modmail DM is disabled and user DMs Modmail from existing thread.
***Default:*** Not Delivered.
***Example:***
* `?config set disabled_current_thread_title Unavailable`
***Notes:***
* Only has an effect when `{prefix}disable all` is set.
* See also: `disabled_current_thread_response`, `disabled_current_thread_footer`, `disabled_new_thread_title`.
### Disabled New Thread Footer ( disabled\_new\_thread\_footer )
The footer of the message embed when Modmail new thread creation is disabled and user tries to create a new thread.
***Default:*** Please try again later...
***Example:***
* `?config set disabled_new_thread_footer Contact us later`
***Notes:***
* Only has an effect when `{prefix}disable` or `{prefix}disable all` is set.
* See also: `disabled_new_thread_title`, `disabled_new_thread_response`, `disabled_current_thread_footer`.
### Disabled New Thread Response ( disabled\_new\_thread\_response )
The body of the message embed when Modmail new thread creation is disabled and user tries to create a new thread.
***Default:*** We are not accepting new threads.
***Example:***
* `?config set disabled_new_thread_response Our working hours is between 8am - 6pm EST.`
***Notes:***
* Only has an effect when `{prefix}disable` or `{prefix}disable all` is set.
* See also: `disabled_new_thread_title`, `disabled_new_thread_footer`, `disabled_current_thread_response`.
### Disabled New Thread Title ( disabled\_new\_thread\_title )
The title of the message embed when Modmail new thread creation is disabled and user tries to create a new thread.
***Default:*** Not Delivered.
***Example:***
* `?config set disabled_new_thread_title Closed`
***Notes:***
* Only has an effect when `{prefix}disable` or `{prefix}disable all` is set.
* See also: `disabled_new_thread_response`, `disabled_new_thread_footer`, `disabled_current_thread_title`.
### Private Added To Group Description Anon ( private\_added\_to\_group\_description\_anon )
This is the message embed content sent to the recipient that is just added to a thread when adduser is used anonymously.
***Default:*** A moderator has added you to a Modmail thread.
***Example:***
* `?config set private_added_to_group_description_anon Any message sent here will be sent to all other thread recipients.`
***Notes:***
* When adduser (no anon) is used, `private_added_to_group_description` is used instead.
* The public\_ variant is used when sending to other thread recipients.
* See also: `private_added_to_group_title`, `public_added_to_group_description_anon`
### Private Added To Group Response ( private\_added\_to\_group\_response )
This is the message embed content sent to the recipient that is just added to a thread.
***Default:*** "{{moderator.name}} has added you to a Modmail thread."
***Example:***
* `?config set private_added_to_group_description Any message sent here will be sent to all otherthread recipients.`
***Notes:***
* You may use the `{{moderator}}` variable for access to the [Member](https://discordpy.readthedocs.io/en/latest/api.html#discord.Member) that added the user.
* When anonadduser is used, `private_added_to_group_description_anon` is used instead.
* The public\_ variant is used when sending to other thread recipients.
* See also: `private_added_to_group_title`, `public_added_to_group_description`
### Private Added To Group Title ( private\_added\_to\_group\_title )
This is the message embed title sent to the recipient that is just added to a thread.
***Default:*** New Thread (Group)
***Example:***
* `?config set private_added_to_group_title Welcome to this new group thread!`
***Notes:***
* The public\_ variant is used when sending to other thread recipients.
* See also: `private_added_to_group_description`, `public_added_to_group_title`
### Private Removed From Group Description Anon ( private\_removed\_from\_group\_description\_anon )
This is the message embed content sent to the recipient that is just removed from a thread when removeuser is used anonymously.
***Default:*** A moderator has removed you from the Modmail thread.
***Example:***
* `?config set private_removed_from_group_description_anon You are permenantly removed from this thread.`
***Notes:***
* When adduser (no anon) is used, `private_removed_from_group_description` is used instead.
* The public\_ variant is used when sending to other thread recipients.
* See also: `private_removed_from_group_title`, `public_removed_from_group_description_anon`
### Private Removed From Group Response ( private\_removed\_from\_group\_response )
This is the message embed content sent to the recipient that is just removed from a thread.
***Default:*** "{{moderator.name}} has removed you from the Modmail thread."
***Example:***
* `?config set private_removed_from_group_description Bye`
***Notes:***
* You may use the `{{moderator}}` variable for access to the [Member](https://discordpy.readthedocs.io/en/latest/api.html#discord.Member) that added the user.
* When anonremoveuser is used, `private_removed_from_group_description_anon` is used instead.
* The public\_ variant is used when sending to other thread recipients.
* See also: `private_removed_from_group_title`, `public_removed_from_group_description`
### Private Removed From Group Title ( private\_removed\_from\_group\_title )
This is the message embed title sent to the recipient that is just removed from a thread.
***Default:*** Removed From Thread (Group)
***Example:***
* `?config set private_removed_from_group_title Welcome to this new group thread!`
***Notes:***
* The public\_ variant is used when sending to other thread recipients.
* See also: `private_removed_from_group_description`, `public_removed_from_group_title`
### Public Added To Group Description Anon ( public\_added\_to\_group\_description\_anon )
This is the message embed content sent to all other recipients when someone is added to the thread when adduser is used anonymously.
***Default:*** "A moderator has added {{users}} to the Modmail thread."
***Example:***
* `?config set public_added_to_group_description_anon Any message sent here will be sent to all other thread recipients.`
***Notes:***
* When adduser (no anon) is used, `public_added_to_group_description` is used instead.
* The private\_ variant is used when sending to the new user.
* See also: `public_added_to_group_title`, `private_added_to_group_description_anon`
### Public Added To Group Response ( public\_added\_to\_group\_response )
This is the message embed content sent to all other recipients when someone is added to the thread.
***Default:*** "{{moderator.name}} has added {{users}} to the Modmail thread."
***Example:***
* `?config set public_added_to_group_response Welcome {users}!`
***Notes:***
* You may use the `{{moderator}}` variable for access to the [Member](https://discordpy.readthedocs.io/en/latest/api.html#discord.Member) that added the user.
* When anonadduser is used, `public_added_to_group_description_anon` is used instead.
* The private\_ variant is used when sending to the new user.
* See also: `public_added_to_group_title`, `private_added_to_group_description`
### Public Added To Group Title ( public\_added\_to\_group\_title )
This is the message embed title sent to all other recipients when someone is added to the thread.
***Default:*** New User
***Example:***
* `?config set public_added_to_group_title Welcome to our new user!`
***Notes:***
* The private\_ variant is used when sending to the new user.
* See also: `private_added_to_group_title`, `private_added_to_group_title`
### Public Removed From Group Description Anon ( public\_removed\_from\_group\_description\_anon )
This is the message embed content sent to all other recipients when someone is removed from the thread when removeuser is used anonymously.
***Default:*** "A moderator has removed {{users}} from the Modmail thread."
***Example:***
* `?config set public_removed_from_group_description_anon Goodbye {users}!`
***Notes:***
* When adduser (no anon) is used, `public_removed_from_group_description` is used instead.
* The private\_ variant is used when sending to the new user.
* See also: `public_removed_from_group_title`, `private_removed_from_group_description_anon`
### Public Removed From Group Response ( public\_removed\_from\_group\_response )
This is the message embed content sent to all other recipients when someone is removed from the thread.
***Default:*** "{{moderator.name}} has removed {{users}} from the Modmail thread."
***Example:***
* `?config set public_removed_from_group_response Goodbye {users}!`
***Notes:***
* You may use the `{{moderator}}` variable for access to the [Member](https://discordpy.readthedocs.io/en/latest/api.html#discord.Member) that added the user.
* When anonremoveuser is used, `public_removed_from_group_description_anon` is used instead.
### Public Removed From Group Title ( public\_removed\_from\_group\_title )
This is the message embed title sent to all other recipients when someone is removed from the thread.
***Default:*** User Removed
***Example:***
* `?config set public_removed_from_group_title User is now gone!`
***Notes:***
* The private\_ variant is used when sending to the new user.
* See also: `private_removed_from_group_title`, `private_removed_from_group_title`
### React To Contact Message ( react\_to\_contact\_message )
A message ID where reactions are tracked. If the `react_to_contact_emoji` is added, the bot opens a thread with them.
***Default:*** None
***Example:***
* `?config set react_to_contact_message 773575608814534717`
***Notes:***
* See also: `react_to_contact_emoji`
### Recipient Thread Close ( recipient\_thread\_close )
Setting this configuration will allow recipients to use the `close_emoji` to close the thread themselves.
***Default:*** Disabled
***Example:***
* `?config set recipient_thread_close yes`
* `?config set recipient_thread_close no`
***Notes:***
* The close emoji is dictated by the configuration `close_emoji`.
* See also: `close_emoji`.
### Thread Auto Close Response ( thread\_auto\_close\_response )
This is the message to display when the thread when the thread auto-closes.
***Default:*** "This thread has been closed automatically due to inactivity after {{timeout}}."
***Example:***
* `?config set thread_auto_close_response Your close message here.`
***Notes:***
* Its possible to use `{{timeout}}` as a placeholder for a formatted timeout text.
* This will not have an effect when `thread_auto_close_silently` is enabled.
* Discord flavoured markdown is fully supported in `thread_auto_close_response`.
* See also: `thread_auto_close`, `thread_auto_close_silently`.
### Thread Auto Close Silently ( thread\_auto\_close\_silently )
Setting this configuration will close silently when the thread auto-closes.
***Default:*** No
***Example:***
* `?config set thread_auto_close_silently yes`
* `?config set thread_auto_close_silently no`
***Notes:***
* This will only have an effect when `thread_auto_close` is set.
* See also: `thread_auto_close`.
### Thread Cancelled ( thread\_cancelled )
This is the message to display when a thread times out and creation is cancelled.
***Default:*** "Cancelled"
***Example:***
* `?config set thread_cancelled Gone.`
### Thread Close Footer ( thread\_close\_footer )
This is the message embed footer sent to the recipient upon the closure of a thread.
***Default:*** "Replying will create a new thread"
***Example:***
* `?config set thread_close_footer Bye!`
***Notes:***
* See also: `thread_close_title`, `thread_close_response`, `thread_creation_footer`.
### Thread Close Response ( thread\_close\_response )
This is the message embed content sent to the recipient upon the closure of a thread.
There are three variables you can use within the thread close message: - `closer`: the discord User object of the user who closed the thread. - `logkey`: the key for the thread logs. (ie. 51ecd946dc29) - `loglink`: the full link URL to the thread logs. (ie. )
***Default:*** "{{closer.mention}} has closed this Modmail thread"
***Example:***
* `?config set thread_close_response Your message is appriciated!`
To use variables in the thread close message:
* `?config set thread_close_response {closer.mention} has closed this thread, here's your log key: **`{logkey}`**.`
***Notes:***
* When `recipient_thread_close` is enabled and the recipient closed their own thread, `thread_self_close_response` is used instead of this configuration.
* You may use the `{{closer}}` variable for access to the [Member](https://discordpy.readthedocs.io/en/latest/api.html#discord.Member) that closed the thread.
* Discord flavoured markdown is fully supported in `thread_close_response`.
* See also: `thread_close_title`, `thread_close_footer`, `thread_self_close_response`, `thread_creation_response`.
### Thread Close Title ( thread\_close\_title )
This is the message embed title sent to the recipient upon the closure of a thread.
***Default:*** "Thread Closed"
***Example:***
* `?config set thread_close_title Farewell!`
***Notes:***
* See also: `thread_close_response`, `thread_close_footer`, `thread_creation_title`.
### Thread Contact Silently ( thread\_contact\_silently )
Setting this configuration will always open a new thread silently in contact.
***Default:*** No
***Example:***
* `?config set thread_contact_silently yes`
* `?config set thread_contact_silently no`
***Notes:***
* Works like `{prefix}contact silent` for every new thread.
### Thread Creation Contact Response ( thread\_creation\_contact\_response )
This is the message embed description sent to recipients when contacted by a mod.
***Default:*** "{{creator.name}} has opened a Modmail thread."
***Example:***
* `?config set thread_creation_contact_response New thread opened.`
***Notes:***
* You may use the `{{creator}}` variable for access to the [Member](https://discordpy.readthedocs.io/en/latest/api.html#discord.Member) that created the thread.
* `thread_creation_self_contact_response` is used when contacted by self.
* See also: `thread_creation_contact_title`, `thread_creation_self_contact_response`.
### Thread Creation Contact Title ( thread\_creation\_contact\_title )
This is the message embed title sent to recipients when contacted.
***Default:*** "New Thread"
***Example:***
* `?config set thread_creation_contact_title New Message!`
***Notes:***
* See also: `thread_creation_self_contact_response`, `thread_creation_contact_response`.
### Thread Creation Footer ( thread\_creation\_footer )
This is the message embed footer sent to the recipient upon the creation of a new thread.
***Default:*** "Your message has been sent"
***Example:***
* \`?config set thread\_creation\_footer Please Hold...
***Notes:***
* This is used in place of `thread_self_closable_creation_footer` when `recipient_thread_close` is enabled.
* See also: `thread_creation_title`, `thread_creation_response`, `thread_self_closable_creation_footer`, `thread_close_footer`.
### Thread Creation Response ( thread\_creation\_response )
This is the message embed content sent to the recipient upon the creation of a new thread.
***Default:*** "The staff team will get back to you as soon as possible."
***Example:***
* `?config set thread_creation_response You will be contacted shortly.`
***Notes:***
* Discord flavoured markdown is fully supported in `thread_creation_response`.
* See also: `thread_creation_title`, `thread_creation_footer`, `thread_close_response`.
### Thread Creation Self Contact Response ( thread\_creation\_self\_contact\_response )
This is the message embed description sent to recipients when self-contacted.
***Default:*** "You have opened a Modmail thread."
***Example:***
* `?config set thread_creation_self_contact_response You contacted yourself.`
***Notes:***
* `thread_creation_contact_response` is used when contacted by another user.
* See also: `thread_creation_contact_title`, `thread_creation_contact_response`.
### Thread Creation Title ( thread\_creation\_title )
This is the message embed title sent to the recipient upon the creation of a new thread.
***Default:*** "Thread Created"
***Example:***
* `?config set thread_creation_title Hello!`
***Notes:***
* See also: `thread_creation_response`, `thread_creation_footer`, `thread_close_title`.
### Thread Move Response ( thread\_move\_response )
This is the message to display to the user when the thread is moved.
***Default:*** This thread has been moved.
***Example:***
* `?config set thread_move_response This thread has been moved to another category for review!`
***Notes:***
* Only has an effect when `thread_move_notify` is on.
* See also: `thread_move_title`, `thread_move_notify`.
### Thread Move Title ( thread\_move\_title )
The title of the message embed when a thread is moved.
***Default:*** Thread Moved
***Example:***
* `?config set thread_move_title Thread transferred to another channel!`
***Notes:*** -See also: `thread_move_notify`, `thread_move_notify_mods`, `thread_move_response`.
### Thread Self Closable Creation Footer ( thread\_self\_closable\_creation\_footer )
This is the message embed footer sent to the recipient upon the creation of a new thread.
***Default:*** "Click the lock to close the thread"
***Example:***
* `?config set thread_self_closable_creation_footer Please Hold...`
***Notes:***
* This is used in place of `thread_creation_footer` when `recipient_thread_close` is disabled.
* See also: `thread_creation_title`, `thread_creation_response`, `thread_creation_footer`.
### Thread Self Close Response ( thread\_self\_close\_response )
This is the message embed content sent to the recipient upon the closure of a their own thread.
***Default:*** "You have closed this Modmail thread."
***Example:***
* `?config set thread_self_close_response You have closed your own thread...`
***Notes:***
* When `recipient_thread_close` is disabled or the thread wasn't closed by the recipient, `thread_close_response` is used instead of this configuration.
* You may use the `{{closer}}` variable for access to the [Member](https://discordpy.readthedocs.io/en/latest/api.html#discord.Member) that closed the thread.
* `{{loglink}}` can be used as a placeholder substitute for the full URL linked to the thread in the log viewer and `{{loglink}}` for the unique key (ie. s3kf91a) of the log.
* Discord flavoured markdown is fully supported in `thread_self_close_response`. -See also: `thread_close_title`, `thread_close_footer`, `thread_close_response`.
## `.env` Config Options
**The following is a list of config options that can \_ONLY**\_\*\* be added by editing the `.env` file. Please use whichever guide you followed to set up the bot to see how to add these variables.\*\*
{% hint style="danger" %}
It is recommended you avoid and ignore changing any of these you do not fully understand
{% endhint %}
| Option | Description | Required | Usage |
| ------------------------ | :---------------------------------------------------------------------------: | :------: | :-------------------------------------------------------------------------------------: |
| modmail\_guild\_id | Inbox server for tickets | No | `MODMAIL_GUILD_ID = GUILDIDHERE` |
| guild\_id | Main server the bot is in | Yes | `GUILD_ID = GUILDIDHERE` |
| log\_url\_prefix | Default is `/logs` | Yes | `LOG_URL_PREFIX = PREFIX` |
| mongo\_uri | The connection uri for the database | Yes | `MONGO_URI = mongodb+srv://Papiersnipper:mypassword123@modmail-rdm99.mongodb.net/` |
| connection\_uri | The connection uri for the database | Yes | `CONNECTION_URI = mongodb+srv://Papiersnipper:mypassword123@modmail-rdm99.mongodb.net/` |
| owners | ID's of the users who will have owner perms | Yes | `OWNERS = 1234,5678,91011` |
| enable\_presence\_intent | Enables the presence intent, required for some plugins. Uses extra resources. | No | `ENABLE_PRESENCE_INTENT = True` |
| registry\_plugins\_only | Disallows the ability to download plugins that aren’t in the plugin registry. | No | `REGISTRY_PLUGINS_ONLY = True` |
| token | The bots token | Yes | `TOKEN = MTAyMjk2NTA4MzYxtewgw3eNw.thisis.afaketoken-WGjwfvQ` |
| enable\_eval | Enables the eval command to run arbitrary code on the bot. | No | `ENABLE_EVAL = True` |
| github\_token | Needed to use the update command | No | `GITHUB_TOKEN = ghp_ABC132gfdsg4321fds` |
| disable\_autoupdates | Allows for auto updates | No | `DISABLE_AUTOUPDATES = True` |
| disable\_updates | Disables updates all together | No | `DISABLE_UPDATES = True` |
| log\_level | The type of information posted in the terminal, Default is `INFO` | No | `LOG_LEVEL = ERROR/WARNING/INFO/DEBUG/NOTSET` |
# Permissions
How to use permissions in modmail.
The modmail bot comes with an advanced permission system that makes it able to choose which individual users or users with certain roles can use modmail specific commands.
The permission levels are the following:
* Owner \[5]
* Administrator \[4]
* Moderator \[3]
* Supporter \[2]
* Regular \[1]
You can view each permission level that is required for the specific command inside the help command.
## Setting up permissions
These permissions can added in two different ways.
### Adding a level to a role or user
`?permissions add level [name] [role/user]`
Examples:
* `?perms add level Regular everyone`
* `?perms add level Moderator @mods`
* `?perms add level Owner @user`
### Adding a command to a role or user
`?permissions add command [name] [role/user]`
Examples:
* `?perms add command reply @user`
* `?perms add command "plugin enabled" @role`
* `?perms add command help 984301093849028`
## Override Permission Level
In some cases it can be useful to override a command permission level. This can be done like this:
`?permissions override `
Examples:
* `?perms override reply administrator`
* `?perms override "plugin enabled" moderator`
### Bulk Permissions Override
Starting in v4.2.2 (check version with `?about`), permissions can be overridden in bulk. To start the process run:
`?permissions override bulk`
***
If you need help setting up permissions, feel free to join our [Discord server](https://discord.gg/zmdYe3ZVHG) and DM Modmail. One of our support members will help you.
# Thread Menu
Instructions on using the threadmenu function of the bot.
{% hint style="info" %}
This page will provide information on using the `?threadmenu` core bot functionality. If you are still using the `advanced-menu` plugin from Sebkuip, please migrate away from the plugin before attempting to use these features.
Migration Instructions are at the bottom of this page.
{% endhint %}
The Thread Menu `?threadmenu` function allows recipients to choose an option to better clarify what kind of help they are recieving. It supports submenus, command, and text-based replys allowing a complex and efficient thread routing system.
## Config Options
| Config Variable Name | Type | Default | Details |
| ------------------------------------------------ | --------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| thread\_creation\_menu\_anonymous\_menu | Boolean (`yes/no`) | No | If enabled, the initial menu prompt relayed to staff (after creation) is anonymized; only selection details are logged, not the original prompt message author context. |
| thread\_creation\_menu\_close\_on\_timeout | Boolean (`yes/no`) | No | Silently aborts thread creation if the user does not select an option before the timeout expires. |
| thread\_creation\_menu\_dropdown\_placeholder | Text | "Select an option to contact the staff team." | Placeholder text displayed in the dropdown before selection. |
| thread\_creation\_menu\_embed\_color | Hex Code (or Discord Color) | Green | Color for the menu embed's side strip. Accepts hex (e.g. #5865F2) or one of the supported color names (e.g. "blurple"). |
| thread\_creation\_menu\_embed\_footer | Text | Empty (no footer) | Optional footer text at the bottom of the menu embed. |
| thread\_creation\_menu\_embed\_footer\_icon\_url | URL | Empty (no icon) | Optional URL for the small footer icon displayed next to the footer text. |
| thread\_creation\_menu\_embed\_image\_url | URL | Empty (no image) | Optional large hero image displayed in the body of the menu embed. If set, this image is shown prominently and takes precedence over the thumbnail. |
| thread\_creation\_menu\_embed\_large\_image | Boolean (`yes/no`) | No | Promotes the thumbnail to a large hero image when no `thread_creation_menu_embed_image_url` is set. Useful if you want a big image without specifying a separate URL. |
| thread\_creation\_menu\_embed\_text | Text | "Please select an option." | Text shown in the embed above the selection dropdown in the user's DM. |
| thread\_creation\_menu\_embed\_thumbnail\_url | URL | Empty (no thumbnail) | Optional thumbnail image shown in the top-right of the menu embed. |
| thread\_creation\_menu\_embed\_title | Text | Empty (no title) | Optional title at the top of the thread-creation menu embed in the user's DM. |
| thread\_creation\_menu\_precreate\_channel | Boolean (`yes/no`) | No | When enabled, a thread channel is created immediately upon the user's first DM even if the thread creation menu is enabled. The menu is still shown but selection becomes optional and happens after channel creation. |
| thread\_creation\_menu\_selection\_log | Boolean (`yes/no`) | Yes | When disabled, the staff will not see an automatic message with the selection details though commands may still act. |
| thread\_creation\_menu\_timeout | Time in Seconds | 30 | If the timeout is reached, `thread_creation_menu_close_on_timeout` controls whether the attempt is aborted or the user is asked to message again. |
## Commands
* threadmenu
* dump\_config - Dump the current core thread menu config to a file.
* load\_config - Load the thread menu config from an attached file.
* option - Manage main-menu options (add/remove/edit/show).
* add - Interactive wizard to add a main-menu option.
* edit - Interactive wizard to edit a main-menu option.
* remove - Remove a main-menu option by label.
* show - Show detailed information about a main-menu option.
* reset - Reset ALL thread-creation menu settings to their defaults.
* show - Show all current main-menu options.
* submenu - Manage submenus (create/delete/list/show and options within).
* create - Create an empty submenu that can hold nested options.
* delete - Delete a submenu and all its options.
* list - List all submenu keys currently configured.
* option - Manage options within a specific submenu (add/remove/edit).
* add - Interactive wizard to add an option inside a submenu.
* edit - Interactive wizard to edit a submenu option.
* remove - Remove an option from a submenu via an interactive prompt.
* show - Show the options configured inside a submenu.
* toggle - Enable or disable the thread-creation menu.
## Example Flowchart and Command Order
{% hint style="info" %}
This feature allows the creation of very complex menu systems. If you are intending to create a complex menu system, it is recommended to think through the required submenus and options and make your submenus first. Drawing these out in a flowchart like below is a good way to begin this process.
{% endhint %}
{% tabs %}
{% tab title="Flowchart Example" %}
{% endtab %}
{% tab title="Commands Example" %}
\*\*In Progress by theonlystephen\*\*
{% endtab %}
{% tab title="Flowchart Template" %}
\*\*In Progress by theonlystephen\*\*
{% endtab %}
{% endtabs %}
## Advanced/Legacy Usage
Migrating from Legacy advanced-menu Plugin
Migration from the legacy plugin, to core function requires permission to modify the menu. In both, by default, this level is ADMINISTRATOR \[4].
**Step 1: Export Config from `advanced-menu`**
Run the `?advancedmenu dump_config` command to dump the menu config from `advanced-menu`. This will export your menu configuration to a `config.json` file.
The bot will provide you a correcly formatted config.json file. Do not modify this file
**Step 2: Download `config.json` to your local computer**
Press the download button and keep track of where the file was saved. You will need it in the next step.
**Step 3: Import Config to Thread Menu**
Run the `?threadmenu load_config` command, while attaching the downloaded `config.json` to your message.
Attach the config.json file directly to your message.
The import was successful if you see: Successfully loaded config into core.
\##Step 4: Uninstall advancedmenu Plugin
Run the command: `?plugin remove advancedmenu`.
**You're done!**
Good job! You have successfully migrated your `advanced-menu` config to the Thread Menu feature introduced in Modmail 4.2.0.
Menu .json File Structure
{% hint style="warning" %}
This is an **advanced** concept, and is **not** required to make full use of this feature. If you do not have significant experience working with `.json` files, you should not be using any of the information in this section.
{% endhint %}
The `?threadmenu dump_config` command exports your set menu configuration to a `.json` file.
By default, the file is now called `thread_creation_menu_config.json`. You can rename this file without any issue while reimporting.
Note: the `"category_id":` in each menu option is optional, and not required for successful import.
See an example dumped config below:
{% code title="thread\_creation\_menu\_config.json" %}
```json
{
"enabled": true,
"options": {
"discord_events_issues": {
"label": "Discord Events Issues",
"description": "I have questions about Discord Events",
"emoji": "⚠️",
"type": "command",
"callback": "move 1341094680229843026 && anonreply Please provide additional details about the event and the issues you encountered so we can help you out."
},
"report_member(s)": {
"label": "Report Member(s)",
"description": "I want to report a Discord member",
"emoji": "🚨",
"type": "command",
"callback": "move 1341094680229843031 && anonreply Please share any relevant information regarding the member(s) involved, along with a description of the incident.",
"category_id": 1341094680229843031
},
"discord_related_issues": {
"label": "Discord Related issues",
"description": "I have questions regarding the server",
"emoji": "🛠️",
"type": "command",
"callback": "move 1341094680770642004 && anonreply Please describe the issue you're facing in detail so that we can help resolve it as quickly as possible.",
"category_id": 1341094680770642004
},
"discord_appeal": {
"label": "Discord Appeal",
"description": "I want to appeal a Discord ban",
"emoji": "🎟️",
"type": "command",
"callback": "move 1341094680770642007 && anonreply Please provide any additional context or evidence that supports your appeal, and we'll review it promptly.",
"category_id": 1341094680770642007
},
"others": {
"label": "Others",
"description": "My question was not listed",
"emoji": "❓",
"type": "command",
"callback": "move 1341094680770642004 && reply Please let us know the details of your request so we can assist you appropriately.",
"category_id": 1341094680770642004
}
},
"submenus": {},
"timeout": 45,
"close_on_timeout": true,
"anonymous_menu": false,
"embed_text": "Please select an option.",
"dropdown_placeholder": "Select an option to contact the staff team."
}
```
{% endcode %}
# Frequently Asked Questions
A list of commonly asked questions or problems related to Modmail.
#### What is Modmail?
Modmail is a Discord bot, similar to Reddit's Modmail feature. It serves as a shared inbox for server staff to communicate with their users - and vice versa - in a seamless way.
#### Can I invite Modmail?
Unfortunately, due to the nature of the bot, there is not a global invite link. Nonetheless, you can obtain a free copy of Modmail for your server. Follow the official tutorial at . However, if you don’t want the hassle of installing and maintaining Modmail, we offer installation, hosting, and other cool perks for [subscribers](https://buymeacoffee.com/modmaildev).
#### How does Modmail work?
Modmail uses the Discord API to interact with the platform. When someone sends a DM to the bot, it will create a new thread. Members of the moderation team can help the user and once the conversation ended, you will have access to a beautiful log of it online.
#### Is Modmail safe?
Your Modmail bot is safe as long as you don't share your bot's token or the mongodb connection\_uri. If you share your token, a "hacker" can take control over your bot and the connection\_uri would give them access to all stored modmail data. If you shared your bot token or connection\_uri by mistake, regenerate a new token via the Discord Developer Portal and/or the MongoDB Atlas Dashboard.
#### Where is my data stored?
All your data including settings, blocked users, logs, installed plugins etc. are stored in your MongoDB database. The bot files only contain the stuff needed to run the bot. This means you can move your bot to a different host and still have your data intact, as long as you use the same MongoDB URI.
#### Can I request new features?
Modmail is an open-source project, which means you can easily add or request new features. You can make an issue or submit a pull request to the development branch on the repository. [Check out the contribution guidelines.](https://github.com/modmail-dev/modmail/blob/master/CONTRIBUTING.md)
#### How do I become a support member?
To join our support team, join our [Discord server](https://discord.gg/zmdYe3ZVHG). One of the more experienced members will hold an interview to check if you fit the requirements.
#### Can I add commands to the bot?
You can add commands to the bot by using plugins. All currently approved plugins can be found in the `?plugin registry` command. If there is no plugin that fits your desired features you can develop your own plugin, read more about that in the [plugin usage guide](/usage-guide/plugins).
#### My bot is offline, what do I do?
Join our [Discord server](https://discord.gg/zmdYe3ZVHG) and create a post in the "help-me" forum or DM Modmail. One of our support members will assist you and help you fix the issue. Please make sure that you provide the hosting method you use to run modmail and the console logs of your bot (if possible). If the bot appears online again automatically at the same time you can also use `?debug hastebin` (share the link) and let us check why the bot had issues.
#### How can I donate the developers?
You can support the developers on the [Buy me a coffee page](https://buymeacoffee.com/modmaildev). You will also receive various rewards for it.
#### I would like to have threads in a seperate guild inbox, how can I do that?
If you want to use a separate server to the main one as the inbox server (Where threads get relayed to) add the following environment variables into your `.env` file:
* `MODMAIL_GUILD_ID` (the server where messages are sent to)
* `GUILD_ID` (The server where users message from)
{% hint style="info" %}
You can only use one ID for each of these two variables. It´s not supported for more multi-guild setups. The `MODMAIL_GUILD_ID` is optional if the GUILD\_ID is the inbox server.
{% endhint %}
#### How do I assign permissions to my staff members to let them reply to threads?
In order to assign permissions to staff, you need to use the `?permissions add` command. The basic permission level for replying, managing snippets (pre-defined responses) is the `Supporter` level 2. For a common setup, you can assign this level to your staff role. An example command to add the permissions to a role would look like this:
```
?permissions add level 2 @role OR the role ID
```
(you can repeat this command for adding multiple roles).
{% hint style="info" %}
If the bot does not automatically add the permissions to the set main category please check that your Modmail bot has enough permissions to view and edit the category.
{% endhint %}
For detailed permission setup, please take a look at the [permissions usage guide](/usage-guide/permissions)
#### Does anyone get any info when I create my own modmail?
There is not much information we get about your instance of modmail, The only thing what we recieve is the guild-info, For example: The guildname, The amount of members of the guild, the botname, and the bot-owner. Using this we keep track of how many Modmail-instances get created on a monthly/yearly base. ( Only modmail-developers can see this ) You can disable this by adding `DATA_COLLECTION=no` to your `.env` file.
***
#### Discord forces me to apply for priviliged Intents to continue using Modmail, why? What does this mean? (Affects large Discord communities only)
Discord requires bot owners to apply for the usage of priviliged Intents that Modmail uses to offer several functionalities **if your Modmail Bot reaches more than 10,000 Users in total in your server(s)** regardless of the server count. If your bot reaches that user count you need to apply for these intents in the Discord Developer Portal. Official information can be read [here](https://support-dev.discord.com/hc/de/articles/40281523410967-Changes-to-Privileged-Intent-Access-for-Discord-Apps)
If you need any assistance to fill out the intents application form regarding what information to sent to Discord please reach out to us in our support server.
#### I tried installing the dependencies with another Python version and it messed up my Pipfile! How can I get the original Pipfile back?
First remove the broken `Pipfile` and `Pipfile.lock` with:
```bash
rm Pipfile && rm Pipfile.lock
```
Fetch in the changes from the remote repository:
```bash
git fetch origin
```
And then, fetch the original files with:
```bash
git checkout FETCH_HEAD -- Pipfile && git checkout FETCH_HEAD -- Pipfile.lock
```
#### Answer not found?
Feel free to join our [Discord server](https://discord.gg/zmdYe3ZVHG). People will gladly help you with any questions that you have! Just create a post in the "help-me" forum or DM our Modmail.
# Intents Review Process
Assistance from the Modmail Team on the intents review process.
{% hint style="info" %}
This process does not apply to a majority of Modmail user's. The only time a Modmail bot will need to go through Discord's Intent Review Process is in one of the following two cases:
1. *(for bots in only one server):* If the server your bot is in is close to, or above 10,000 members.
2. *(for bots in multiple servers):* If the combined member count of all the servers your bot is in is close to, or above 10,000 members.
{% endhint %}
## Background
Discord uses Gateway Intents to control what information is sent to your bot. Some intents, including **Message Content**, **Server Members**, and **Presence**, are considered **Privileged Intents** because they provide access to data that Discord considers more sensitive from a privacy and security perspective. Discord limits access to these intents to ensure developers only collect the information necessary for their bot's functionality.
Modmail requires the **Message Content Intent** to read user messages and create tickets, and the **Server Members Intent** for user information features. Discord now determines privileged intent review eligibility based on the **total number of users your bot can access**, rather than the number of servers your bot is in. Applications with access to 10,000 or more users must complete Discord's intent review process before using privileged intents. During review, Discord will ask why your bot needs the requested intents and how the data is used.
## Intents Request Form
Intents Application Form for Application Details and Server (Guild) Members Intent
Questions for Prescence Intent (Not Required for Modmail.)
Questions for Message Content Intent and Certification of Answers
## Suggested Responses
### Application Details
> *Q: What does your application do? Please be as detailed as possible...*
{% code title="Question 1" overflow="wrap" %}
```
Modmail is a shared inbox bot for server moderation. When a user sends a Direct Message to the bot, it automatically creates a dedicated text channel (a "thread") within a designated staff category in our Discord server. Server staff can read the user's messages in this channel and reply using bot commands. The bot then relays these staff replies back to the user via Direct Message. This allows for organized, private, and collaborative support between users and the moderation team.
```
{% endcode %}
{% hint style="info" %}
You will need to adopt a privacy policy for your bot. We have a version you can opt to use [here](/faq/privacy-policy).
{% endhint %}
{% hint style="danger" %}
Whether you use our template privacy policy, or another privacy policy of your choosing, it is a legally binding committment between you, and the users who use your bot in most jusrisdictions. Failing to comply with the guidlines, expectations, and promises made in a privacy policy is not only a gross breach of trust, but in some jusrisdictions, illegal, or at a minimum, subject to civil liability.
It is imperative that before adopting any privacy policy you review it personally, and with your team, and continue to review it with new team members as they join your team. As the operator of the bot, you are responsible for ensuring that everyone on your team is compliant with the chosen privacy policy.
{% endhint %}
> *Q: Do you have a public Privacy Policy telling your users about their data usage?*
{% code title="Question 2" overflow="wrap" %}
```
Select: Yes
```
{% endcode %}
{% hint style="info" %}
You'll need to add a link to your bots Privacy Policy to its Bio field via the [Discord Developer Portal](https://discord.com/developers/applications). *The **Description** field on the **General Information** is the text displayed in your bots Bio field.*
{% endhint %}
> *Q: Where is your Privacy Policy available?*
{% code title="Question 3" overflow="wrap" %}
```
The bot has a link to the Privacy Policy in its Bio. As the interaction with the bot occurs via DMs, it is likely that users will see the bot's profile with the Privacy Policy link.
```
{% endcode %}
{% hint style="warning" %}
Only use the Privacy Policy link below if you have chosen to file our published generic privacy policy for bots. If you choose to implement your own, or use the template we provide at the bottom of that page, then you must link that policy instead.
{% endhint %}
> *Q: Please share a link to your Privacy Policy.*
{% code title="Question 4" overflow="wrap" %}
```
https://docs.modmail.dev/frequently-asked-questions/privacy-policy
```
{% endcode %}
### Server Members Intent
> *Q: Why do you need the Server Members intent?*
{% code title="Question 1" overflow="wrap" %}
```
Modmail requires the Server Members Intent to accurately check a user's membership status.
When a user initiates a Direct Message with the bot, the bot must scan the user's shared servers to route the message to the correct server's staff team. Additionally, the bot uses member data to verify staff permissions, ensuring that only authorized moderators can view the modmail threads, use staff commands, and reply to users.
Finally, tracking member leave events is necessary to immediately detect if a user has left the server, informing the moderation team whether replying to the individual is still possible.
```
{% endcode %}
> *Q: Please provide links to screenshots and/or videos that demonstrate your use case*
{% code title="Question 2" overflow="wrap" %}
```
https://youtu.be/jxEbZOMrF9w
```
{% endcode %}
{% hint style="info" %}
Our team is aware that this video does not meet our usual requirements for a polished final result. Once we have additional time, and verification that the details in this video are sufficient, we will release a more polished version to be used in the future.
If you want to record a video using your own bot, you are welcome to do so.
{% embed url="" %}
{% endhint %}
> *Q: Are you storing any API Data off-platform (outside of Discord)?*
{% code title="Question 3" overflow="wrap" %}
```
Select: Yes
```
{% endcode %}
> *Q: Are you storing API Data for 30 days or less?*
{% code title="Question 4" overflow="wrap" %}
```
Select: No
```
{% endcode %}
> *Q: How do users contact you to request deletion of their activity data?*
{% code title="Question 5" overflow="wrap" %}
```
Users can request the deletion of their data by sending a Direct Message to the bot itself to contact the server staff, or by directly messaging one of the server administrators. This information is also contained in the bot's privacy policy.
```
{% endcode %}
> *Q: Are you encrypting the data that you store at rest, as is required by our developer policy?*
{% code title="Question 6" overflow="wrap" %}
```
Select: Yes
```
{% endcode %}
### Message Content Intent
> *Q: Can users opt-out of having their message content data tracked?*
{% code title="Question 1" overflow="wrap" %}
```
Select: Yes
```
{% endcode %}
> *Q: Are you storing message content data off-platform (outside of Discord)?*
{% code title="Question 2" overflow="wrap" %}
```
Select: Yes
```
{% endcode %}
> *Q: Are you storing user message content data for 30 days or less?*
{% code title="Question 3" overflow="wrap" %}
```
Select: No
```
{% endcode %}
{% hint style="info" %}
In almost all cases the answer to the question above (#3) will be No. However, if you have set your log retention period via the config command to 30 days or less, than your answer would be **Yes** instead.
{% endhint %}
> *Q: How do users contact you to request deletion of their activity data?*
{% code title="Question 4" overflow="wrap" %}
```
Users can request the deletion of their data by sending a Direct Message to the bot itself to contact the server staff, or by directly messaging one of the server administrators. This information is also contained in the bot's privacy policy.
```
{% endcode %}
> Q: Are you encrypting the data that you store at rest, as is required by our developer policy?
{% code title="Question 5" overflow="wrap" %}
```
Select: Yes
```
{% endcode %}
> Q: Will the message content data be used to train machine learning or AI Models?
{% code title="Question 6" overflow="wrap" %}
```
Select: No
```
{% endcode %}
{% hint style="info" %}
This may be different for your use case. If you currently, or intend in the future to; use the data Modmail collects for AI training purposes, you would need to select `Yes` for this question.
{% endhint %}
> Q: Why do you need the Message Content intent?
{% code title="Question 6" overflow="wrap" %}
```
The core functionality of Modmail relies on processing, relaying, and logging message content sent within the server's moderation channels. The bot requires the Message Content intent to read the messages sent by staff members inside the server's modmail threads, allowing the bot to forward those replies back to the user. Additionally, the intent is necessary to monitor and log internal staff-only discussions within these server channels to preserve a complete and accurate moderation history for future reference. Without the Message Content intent, the bot cannot detect staff replies or archive internal server logs, rendering the moderation workflow non-functional.
```
{% endcode %}
> Q: Please provide links to screenshots and/or videos that demonstrate your use case
{% code title="Question 7" overflow="wrap" %}
```
https://youtu.be/jxEbZOMrF9w
```
{% endcode %}
### Presence Intent
Presence Intent
While we often recommend the Presence intent to allow for compatibility with a number of third party plugins, it is not a requirement for the core bot.
Our current stance as a team is that if a plugin requires the presence intent, then the plugin developer is responsible for providing an articulatable reason to users to use during the intents review process.
If they require assistance with this, they can contact the Modmail bot in our official [support server](https://discord.gg/cnUpwrnpYb).
# Instance Privacy Policy
Sample Bot Privacy Policy that can be used by instances at their discretion
{% hint style="info" %}
This Privacy Policy only applies to Modmail Instances hosted by administrators who choose to use it. If a bot administrator has provided you this privacy policy, they have agreed to use it for their specific instance. If you have any questions regarding the validity of this privacy policy for any specific Modmail instance, please contact the relevant staff team.
{% endhint %}
Last Updated: July 7th, 2026
This Privacy Policy explains how Modmail (referred to as "the Bot", "we", or "us") collects, uses, stores, and protects your data. The Bot is an instance of the open-source [modmail-dev/modmail](https://github.com/modmail-dev/modmail) project and is hosted independently by the administrators of the Discord server.
By interacting with the Bot, you consent to the data practices described in this policy. This policy is designed to comply with the [Discord Developer Terms of Service](https://support-dev.discord.com/hc/en-us/articles/8562894815383-Discord-Developer-Terms-of-Service) and [Developer Policy](https://support-dev.discord.com/hc/en-us/articles/8563934450327-Discord-Developer-Policy).
## 1. Data We Collect
When you send a direct message to the Bot to initiate a support thread or interact with an active thread, we collect and store the following information:
1. **User Data:** Your Discord User ID, username, and avatar.
2. **Message Content:** The text content, links to attachments, and timestamps of any messages sent to the Bot.
3. **Server Data:** Relevant Guild (Server) IDs and Channel IDs required to route your messages to the correct moderation team.
4. **Action Logs:** Metadata related to the thread, such as when it was opened, closed, or transferred by moderators.
## 2. How We Store Your Data
The [modmail-dev/modmail](https://github.com/modmail-dev/modmail) application does not store data on Discord's infrastructure once a thread is archived ("closed"). Instead, all collected data (including message logs and user identifiers) is exported and stored off-platform in a MongoDB database.
This database is managed independently by the individual or team hosting the Bot instance. We implement reasonable security measures to protect your data from unauthorized access.
## 3. How We Use Your Data
The data we collect is strictly used to provide and maintain the functionality of the Bot. Specifically, we use it for:
1. **Facilitating Communication:** Relaying messages between you and the server's moderation or support staff.
2. **Record Keeping:** Maintaining an accurate history of support requests, appeals, or reports for server staff to reference.
3. **Service Improvement:** Allowing server administrators to review past interactions to improve community guidelines and support responses.
## 4. Data Sharing and Disclosure
Your data is highly restricted. We do not sell, monetize, or trade your personal information. Your data is only accessible to:
1. **Authorized Server Staff:** Moderators and administrators of the Discord server who have the necessary permissions to view Modmail threads and logs.
2. **The Database Administrator:** The technical individual responsible for hosting the MongoDB instance and keeping the Bot online.
3. **MongoDB Atlas Employees:** Select employees of the MongoDB Atlas team may have the ability to access the data. Their usage is restricted and governed by their [privacy policy](https://www.mongodb.com/legal/privacy/privacy-policy).
We will not share your data with any third parties unless explicitly required to do so by law or to comply with Discord's Trust and Safety requests.
## 5. Data Retention
Chat logs and associated user identifiers are retained indefinitely within our MongoDB database to ensure server staff have a consistent historical record of all moderation and support interactions.
## 6. Your Rights and Data Deletion
Under the Discord Developer Policies, you have the right to request the deletion of your personal data. If you wish to have your Modmail logs and associated identifying information permanently removed from our off-platform MongoDB database, you may exercise this right by:
1. Sending a message directly to the Bot requesting data deletion.
2. Contacting the server administrators or the contact person listed below.
Upon receiving a valid request, we will purge your identifying information and message content from our database within 14 days.
## 7. Contact Information
If you have any questions, concerns, or data deletion requests regarding this Privacy Policy or the Bot's operation, please contact:
1. The Bot directly; or
2. Any member of the server's staff team; or
3. The owner of the Discord server.
{% updates format="full" %}
{% update date="2026-07-07" tags="beta" %}
##
Fix typo in last update date.
{% endupdate %}
{% update date="2026-07-05" tags="beta" %}
##
Initial Publication of the Privacy Policy. [Permalink](https://github.com/modmail-dev/modmail-docs/blob/7afe2153184617ac5802cdef9496732235b3cae1/faq/privacy-policy.md)
{% endupdate %}
{% endupdates %}
{% hint style="info" %}
**Server Owners** — If you do not want this one size fits all option, you can use the template below as a starting point.
{% endhint %}
Basic Template
This Privacy Policy explains how `[Insert Bot Name]` (referred to as "the Bot", "we", or "us") collects, uses, stores, and protects your data. This Bot is an instance of the open-source [modmail-dev/modmail](https://github.com/modmail-dev/modmail) project and is hosted independently by the administrators of `[Insert Discord Server Name]`.
By interacting with the Bot, you consent to the data practices described in this policy. This policy is designed to comply with the [Discord Developer Terms of Service](https://support-dev.discord.com/hc/en-us/articles/8562894815383-Discord-Developer-Terms-of-Service) and [Developer Policy](https://support-dev.discord.com/hc/en-us/articles/8563934450327-Discord-Developer-Policy).
1. Data We Collect
When you send a direct message to the Bot to initiate a support thread or interact with an active thread, we collect and store the following information:
1. User Data: Your Discord User ID, username, and avatar.
2. Message Content: The text content, links to attachments, and timestamps of any messages sent to the Bot.
3. Server Data: Relevant Guild (Server) IDs and Channel IDs required to route your messages to the correct moderation team.
4. Action Logs: Metadata related to the thread, such as when it was opened, closed, or transferred by moderators.
5. How We Store Your Data
The [modmail-dev/modmail](https://github.com/modmail-dev/modmail) application does not store data on Discord's infrastructure once a thread is archived. Instead, all collected data (including message logs and user identifiers) is exported and stored off-platform in a MongoDB database.
This database is managed independently by the individual or team hosting this Bot instance. We implement reasonable security measures within the database environment to protect your logs from unauthorized access.
3. How We Use Your Data
The data we collect is strictly used to provide and maintain the functionality of the Bot. Specifically, we use it for:
1. Facilitating Communication: Relaying messages between you and the server's moderation or support staff.
2. Record Keeping: Maintaining an accurate history of support requests, appeals, or reports for the server staff to reference in the future.
3. Service Improvement: Allowing server administrators to review past interactions to improve community guidelines and support responses.
4. Data Sharing and Disclosure
Your data is highly restricted. We do not sell, monetize, or trade your personal information. Your data is only accessible to:
1. Authorized Server Staff: Moderators and administrators of `[Insert Discord Server Name]` who have the necessary permissions to view Modmail threads and logs.
2. The Database Administrator: The technical individual(s) responsible for hosting the MongoDB instance and keeping the Bot online. a. Database Administrator(s): `[Insert Names of Database Administrators Here]`
3. MongoDB Atlas Employees: Select employees of the MongoDB Atlas team may have the ability to access the data. Their usage is restricted and governed by their [privacy policy](https://www.mongodb.com/legal/privacy/privacy-policy).
4. `[Insert Name of Hosting Company]` Employees: Select employees of `[Insert Name of Hosting Company]` are able to access the data due to their ability to access the MongoDB connection information. Their privacy policy is defined \[here]\(`[Insert URL to Hosting Company Privacy Policy Here]`).
We will not share your data with any third parties unless explicitly required to do so by law or to comply with Discord's Trust and Safety requests.
5. Data Retention
Chat logs and associated user identifiers are retained `indefinitely/(OR)[Insert Log Retention Time Here]` within our MongoDB database to ensure server staff have a consistent historical record of all moderation and support interactions.
6. Your Rights and Data Deletion
Under the Discord Developer Policies, you have the right to request the deletion of your personal data. If you wish to have your Modmail logs and associated identifying information permanently removed from our off-platform MongoDB database, you may exercise this right by:
1. Sending a message directly to the Bot requesting data deletion.
2. Contacting the server administrators or the contact person(s) listed below.
Upon receiving a verifiable request, we will manually purge your identifying information and message content from our database within \[Insert Number, e.g., 30] days.
7. Contact Information
If you have any questions, concerns, or data deletion requests regarding this Privacy Policy or the Bot's operation, please contact us at:
1. Discord User(s): `[Insert Discord Username(s) of the Bot Owner/Administrator(s)]`
2. Email: `[Insert Contact Email, if applicable]`
3. Server: `[Insert Invite Link or instructions on how to reach staff]`
{% hint style="warning" %}
**Server Owners**
Please note that by using the Privacy Policy on our Docs site without modification, you are making legally binding promises to your users and to Discord. These promises include, but are not limited to:
**1. Strict Data Sharing Limitations**
You are agreeing that you will not share user data with any third parties unless required by law. This means you cannot share Modmail logs with other Discord servers, community ban lists, global moderation databases, or any external entities. If you do so: you are violating this privacy policy, which could carry civil penalties in some jurisdictions.
**2. Infrastructure and Hosting Trust**
The policy states that only server staff and the database administrator have access to the logs. You must ensure that your hosting provider and your database host are secure and trustworthy. If your hosting provider has weak security and your database leaks, the responsibility falls entirely on you. *(This is primarily a concern for individuals using hosting providers that are not established, see our comments on* [*unrecommended hosts*](/choose-host/unrecommended-hosts)*.)*
**3. Binding Deletion Timelines**
If you state that you will delete data upon request within 14 days, you must have a reliable, manual process to find and purge a user's data from your MongoDB cluster within that exact timeframe. Failure to honor data deletion requests is a direct violation of the Discord Developer Terms of Service and can result in action taken against your account. If you fail to honor this you also: are violating this privacy policy, which could carry civil penalties in some jurisdictions.
**4. Managing Staff Access**
Because your policy guarantees that only authorized staff have access to user data, you must rigorously manage permissions. When a moderator steps down or is removed from your team, you must immediately revoke their access to the Modmail bot commands, the database, and the log viewer. If you fail to do so: you are violating this privacy policy, which could carry civil penalties in some jurisdictions.
**5. Regional Privacy Laws**
Depending on where you and your users reside, you may be subject to strict data protection laws like the GDPR in Europe or the CCPA in California. These laws impose significant obligations regarding data handling, consent, and user rights, even for hobbyist or volunteer-run Discord servers.
{% endhint %}
# Instance Terms of Service
Sample Bot Terms of Service that can be used by instances at their discretion
{% hint style="info" %}
These Terms of Service only apply to Modmail Instances hosted by administrators who choose to use them. If a bot administrator has provided you these terms, they have agreed to use them for their specific instance. If you have any questions regarding the validity of these terms for any specific Modmail instance, please contact the relevant staff team.
{% endhint %}
Last Updated: June 17th, 2026
These Terms of Service ("Terms") govern your use of Modmail (referred to as "the Bot", "we", or "us"). The Bot is an instance of the open-source [modmail-dev/modmail](https://github.com/modmail-dev/modmail) project and is hosted independently by the administrators of the Discord server.
By interacting with the Bot, you agree to be bound by these Terms. If you do not agree, please refrain from using the Bot. These Terms are designed to comply with the [Discord Developer Terms of Service](https://support-dev.discord.com/hc/en-us/articles/8562894815383-Discord-Developer-Terms-of-Service) and [Developer Policy](https://support-dev.discord.com/hc/en-us/articles/8563934450327-Discord-Developer-Policy).
## 1. Description of Service
Modmail is a Discord bot that functions as a shared inbox between server members and staff. It allows users to send direct messages to the Bot, which are then relayed to the server's staff as private threads. Staff can respond through these threads, and the replies are sent back to the user via direct message.
## 2. Eligibility
You must comply with Discord's [Terms of Service](https://discord.com/terms) to use the Bot. By using the Bot, you confirm that you meet the minimum age requirements set by Discord and that your Discord account is in good standing. You must also be a member of the Discord server where the Bot operates to use its services. The Bot will be unavailable to you if you are not a member of the server, or if you have been blocked from using the Bot by the server's staff.
## 3. Acceptable Use
When interacting with the Bot, you agree to:
1. **Use the Bot for its intended purpose:** Communicating with the server's staff through the Modmail system.
2. **Follow the server's rules:** Abide by the community guidelines and rules of the Discord server the Bot operates in.
3. **Not abuse the Bot:** Refrain from spamming, sending unsolicited messages, or otherwise attempting to disrupt the Bot's functionality or the staff's ability to respond.
4. **Not attempt to exploit the Bot:** Do not attempt to reverse-engineer, manipulate, or exploit the Bot's functionality, including its commands, APIs, or data storage.
## 4. Message Content and Conduct
All messages sent to the Bot are relayed to server staff and may be logged for record-keeping purposes. You are solely responsible for the content of your messages. Messages that violate Discord's Terms of Service, contain illegal content, or are deemed abusive may result in action being taken by the server's staff, up to and including being banned from the server.
## 5. Data Collection and Privacy
Your use of the Bot is also governed by our [Privacy Policy](/faq/privacy-policy), which explains what data we collect, how we store it, and your rights regarding that data. By using the Bot, you consent to the data practices described in the Privacy Policy.
## 6. Availability and Modifications
1. **No guarantee of uptime:** The Bot is provided on an "as-is" basis. We do not guarantee that the Bot will be available at all times. The Bot may experience downtime due to maintenance, hosting issues, or other technical factors.
2. **Right to modify:** We reserve the right to modify, update, or discontinue the Bot or any part of its functionality at any time without prior notice.
3. **Right to restrict access:** Server administrators reserve the right to restrict or revoke your access to the Bot at their discretion.
## 7. Limitation of Liability
To the fullest extent permitted by law:
1. The Bot is provided "as-is" and "as available" without warranties of any kind, either express or implied.
2. We are not liable for any damages arising from your use of, or inability to use, the Bot. This includes, but is not limited to, loss of data, service interruptions, or unauthorised access to your messages.
3. The Bot's administrators and the [modmail-dev/modmail](https://github.com/modmail-dev/modmail) project contributors bear no responsibility for the actions of individual server staff or the decisions made based on Modmail thread content.
## 8. Third-Party Services
The Bot relies on the following third-party services to function:
1. **Discord:** The Bot operates on the Discord platform and is subject to Discord's [Terms of Service](https://discord.com/terms) and [Privacy Policy](https://discord.com/privacy).
2. **MongoDB:** Message logs and user data are stored in a MongoDB database, subject to MongoDB's [privacy policy](https://www.mongodb.com/legal/privacy/privacy-policy).
We are not responsible for the practices, policies, or availability of these third-party services.
## 9. Termination
Server administrators may revoke your access to the Bot at any time for any reason. If you wish to stop using the Bot, simply refrain from sending it direct messages. Data already collected will be retained in accordance with our [Privacy Policy](/faq/privacy-policy) unless you submit a deletion request.
## 10. Changes to These Terms
We reserve the right to update these Terms at any time. Continued use of the Bot after changes are made constitutes acceptance of the revised Terms. We encourage you to review these Terms periodically.
## 11. Contact Information
If you have any questions or concerns regarding these Terms, please contact:
1. The Bot directly; or
2. Any member of the server's staff team; or
3. The owner of the Discord server.
***
{% hint style="info" %}
**Server Owners** — If you do not want this one size fits all option, you can use the template below as a starting point.
Basic Template
These Terms of Service ("Terms") govern your use of `[Insert Bot Name]` (referred to as "the Bot", "we", or "us"). The Bot is an instance of the open-source [modmail-dev/modmail](https://github.com/modmail-dev/modmail) project and is hosted independently by the administrators of `[Insert Discord Server Name]`.
By interacting with the Bot, you agree to be bound by these Terms. If you do not agree, please refrain from using the Bot. These Terms are designed to comply with the [Discord Developer Terms of Service](https://support-dev.discord.com/hc/en-us/articles/8562894815383-Discord-Developer-Terms-of-Service) and [Developer Policy](https://support-dev.discord.com/hc/en-us/articles/8563934450327-Discord-Developer-Policy).
1. Description of Service
Modmail is a Discord bot that functions as a shared inbox between server members and staff. It allows users to send direct messages to the Bot, which are then relayed to the server's staff as private threads. Staff can respond through these threads, and the replies are sent back to the user via direct message.
2. Eligibility
You must comply with Discord's [Terms of Service](https://discord.com/terms) to use the Bot. By using the Bot, you confirm that you meet the minimum age requirements set by Discord and that your Discord account is in good standing. You must also be a member of `[Insert Discord Server Name]` to use its services. The Bot will be unavailable to you if you are not a member of the server, or if you have been blocked from using the Bot by the server's staff.
3. Acceptable Use
When interacting with the Bot, you agree to:
1. Use the Bot for its intended purpose: Communicating with the server's staff through the Modmail system.
2. Follow the server's rules: Abide by the community guidelines and rules of `[Insert Discord Server Name]`.
3. Not abuse the Bot: Refrain from spamming, sending unsolicited messages, or otherwise attempting to disrupt the Bot's functionality.
4. Not attempt to exploit the Bot: Do not attempt to reverse-engineer, manipulate, or exploit the Bot's functionality, including its commands, APIs, or data storage.
5. Message Content and Conduct
All messages sent to the Bot are relayed to server staff and may be logged for record-keeping purposes. You are solely responsible for the content of your messages. Messages that violate Discord's Terms of Service, contain illegal content, or are deemed abusive may result in action being taken by the server's staff, up to and including being banned from the server.
5. Data Collection and Privacy
Your use of the Bot is also governed by our Privacy Policy, which explains what data we collect, how we store it, and your rights regarding that data. By using the Bot, you consent to the data practices described in the Privacy Policy.
6. Availability and Modifications
7. No guarantee of uptime: The Bot is provided on an "as-is" basis. We do not guarantee that the Bot will be available at all times.
8. Right to modify: We reserve the right to modify, update, or discontinue the Bot or any part of its functionality at any time without prior notice.
9. Right to restrict access: Server administrators reserve the right to restrict or revoke your access to the Bot at their discretion.
10. Limitation of Liability
To the fullest extent permitted by law:
1. The Bot is provided "as-is" and "as available" without warranties of any kind, either express or implied.
2. We are not liable for any damages arising from your use of, or inability to use, the Bot.
3. The Bot's administrators and the [modmail-dev/modmail](https://github.com/modmail-dev/modmail) project contributors bear no responsibility for the actions of individual server staff or the decisions made based on Modmail thread content.
4. Third-Party Services
The Bot relies on the following third-party services to function:
1. Discord: The Bot operates on the Discord platform and is subject to Discord's [Terms of Service](https://discord.com/terms) and [Privacy Policy](https://discord.com/privacy).
2. MongoDB: Message logs and user data are stored in a MongoDB database, subject to MongoDB's [privacy policy](https://www.mongodb.com/legal/privacy/privacy-policy).
3. `[Insert Name of Hosting Company]`: The Bot is hosted by `[Insert Name of Hosting Company]`, subject to their \[terms of service]\(`[Insert URL to Hosting Company ToS Here]`).
We are not responsible for the practices, policies, or availability of these third-party services.
9. Termination
Server administrators may revoke your access to the Bot at any time for any reason. If you wish to stop using the Bot, simply refrain from sending it direct messages. Data already collected will be retained in accordance with our Privacy Policy unless you submit a deletion request.
10. Changes to These Terms
We reserve the right to update these Terms at any time. Continued use of the Bot after changes are made constitutes acceptance of the revised Terms.
11. Contact Information
If you have any questions or concerns regarding these Terms, please contact:
1. Discord User(s): `[Insert Discord Username(s) of the Bot Owner/Administrator(s)]`
2. Email: `[Insert Contact Email, if applicable]`
3. Server: `[Insert Invite Link or instructions on how to reach staff]`
{% endhint %}
{% hint style="warning" %}
**Server Owners**
Please note that by using the Terms of Service on our Docs site without modification, you are making legally binding promises to your users and to Discord. These promises include, but are not limited to:
**1. Liability Limitations**
You are claiming that the Bot is provided "as-is" and that you bear no liability for damages. While this is standard, the enforceability of liability limitations varies by jurisdiction. In some regions (particularly within the EU), blanket liability disclaimers may not be enforceable against consumers. You should be aware of the laws applicable to your users.
**2. Availability Commitments**
By stating that you do not guarantee uptime, you are setting the expectation that the Bot may be unavailable at times. However, if you consistently fail to maintain the Bot or abandon it without notice while still collecting user data, you may be in violation of your obligations under the Discord Developer Terms of Service.
**3. Third-Party Service Accountability**
The Terms reference Discord and MongoDB as third-party services. If you use additional services (such as a specific hosting provider), you must either use the template to disclose them or accept that you have not fully informed your users about where their data may be processed.
**4. Enforcing Acceptable Use**
Your Terms prohibit abusive behaviour and Bot exploitation. If you fail to consistently enforce these rules, or if you yourself violate the acceptable use standards (e.g., using the Bot to harass users), you undermine the legitimacy of your own Terms and may face consequences from Discord.
**5. Consistency with Privacy Policy**
These Terms reference the Privacy Policy. If the two documents contradict each other (e.g., your Terms claim data is deleted immediately but your Privacy Policy states a 14-day window), the inconsistency could create legal exposure. Ensure both documents are aligned.
{% endhint %}
# Config References
https\://github.com/modmail-dev/modmail
Modmail is a self-hosted Discord bot for your server. It works similar to [Reddit](https://reddit.zendesk.com/hc/en-us/articles/210896606-What-is-Modmail-)'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 [**BuyMeACoffee**](https://buymeacoffee.com/modmaildev/membership), cool benefits included!
## What is Modmail used for?
When a member sends a direct message to Modmail, the bot will create a channel (we call it a "thread") into a designated category. All further DM messages will automatically relay to that channel, then any available staff can respond within the channel. Compared to ticketing bots, Modmail allows easier and more organised discussions among staff.
An example of a Modmail thread.
Our Logviewer will save the threads so your staff can view previous threads through their corresponding log link. ~~Here is an~~ [~~**example**~~](https://publicmodmail.logs.vodka/logs/example).
## Features
#### **Highly customisable**
* Changeable bot status, prefix, category, log channel, etc.
* Versatile command permission system.
* Interface elements (color, responses, reactions, etc.).
* Snippets and command aliases.
* Minimum durations for account age and time in server before allowed to contact Modmail.
* Plugin support for extending functionality.
* Custom thread creation messages and thread naming formats.
* Configurable auto-close, inactivity, and notification settings.
**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.
* Discord authentication-protected logs ([Patreon/BMAC-only feature](https://buymeacoffee.com/modmaildev/membership)).
* See past logs of a user with `?logs`.
* Searchable by text queries using `?logs search`.
#### **Robust implementation**
* Ease of installation: you can get your Modmail bot running in under 10 minutes!
* Schedule tasks in human time, e.g. `?close in 2 hours silently`.
* Editing and deleting messages are synced.
* Support for images, files, stickers, and other attachments.
* Internal notes and moderator-only discussions.
* Paginated commands interfaces via buttons.
* Multi-user conversations and private thread management tools.
This list is ever-growing thanks to active development by our exceptional contributors. See a full list of available commands by using the `?help` command.
## Installation
Visit our [installation page](/installation) for detailed instructions on setting up Modmail for your server.
## Supporting the project
You have various options to help the project. Giving this repository a star is greatly appreciated. You can also help people that have trouble setting up Modmail at our [Discord server](https://discord.gg/cnUpwrnpYb).
## Contributing
Support Modmail with your contributions! Whether it be improvements to the documentation or new functionality, please feel free to make the change. Check out our [contributing guidelines](https://github.com/modmail-dev/modmail/blob/master/.github/CONTRIBUTING.md) before you get started.
## Next Steps
* Read about [installing Modmail](/installation).
* Become familiar with [Modmail commands and functionalities](https://github.com/kyb3rr/modmail-docs/tree/main/getting-started.md).
{% hint style="info" %}
Throughout this documentation when we're referring to bot commands, we will assume the prefix of the bot to be ? and will display them like in this example: ?help.\
\
**Optional** arguments will be enclosed in square brackets:\
Example: ?close \[time] \[reason] \[silently]\
\
**Required** arguments will be enclosed in angle brackets:\
Example: ?contact \
{% endhint %}
# Configuration Variables
These are currently all the valid configuration variables you can change with the `config set` command.
### This page has been pulled due to factual inaccuracies due to the assistance of Generative AI technologies. It will be redone by humans without assistance and be reuploaded as soon as possible.
> I appreciate your understanding and apologize I did not fully check the AI version before publishing. -Stephen from the Modmail Team
# Color Names
## Color Names
Color Names can be used for `mod_color`, `recipient_color`, and `main_color` configuration variables.
***
### Base Colors:
| Color Name | Hex Code |
| ---------- | ------------------------------------------------------------------------- |
| b |  `#0000ff` |
| g |  `#007f00` |
| r |  `#ff0000` |
| c |  `#00bfbf` |
| m |  `#bf00bf` |
| y |  `#bfbf00` |
| k |  `#000000` |
| w |  `#ffffff` |
***
### Tableau Colors:
| Color Name | Hex Code |
| ---------- | ------------------------------------------------------------------------- |
| blue |  `#1f77b4` |
| orange |  `#ff7f0e` |
| green |  `#2ca02c` |
| red |  `#d62728` |
| purple |  `#9467bd` |
| brown |  `#8c564b` |
| pink |  `#e377c2` |
| gray |  `#7f7f7f` |
| olive |  `#bcbd22` |
| cyan |  `#17becf` |
To force use tableau color, use `tab:` (ie. `tab:red`).
***
### XKCD Colors:
| Color Name | Hex Code |
| -------------------------- | ------------------------------------------------------------------------- |
| cloudy blue |  `#acc2d9` |
| dark pastel green |  `#56ae57` |
| dust |  `#b2996e` |
| electric lime |  `#a8ff04` |
| fresh green |  `#69d84f` |
| light eggplant |  `#894585` |
| nasty green |  `#70b23f` |
| really light blue |  `#d4ffff` |
| tea |  `#65ab7c` |
| warm purple |  `#952e8f` |
| yellowish tan |  `#fcfc81` |
| cement |  `#a5a391` |
| dark grass green |  `#388004` |
| dusty teal |  `#4c9085` |
| grey teal |  `#5e9b8a` |
| macaroni and cheese |  `#efb435` |
| pinkish tan |  `#d99b82` |
| spruce |  `#0a5f38` |
| strong blue |  `#0c06f7` |
| toxic green |  `#61de2a` |
| windows blue |  `#3778bf` |
| blue blue |  `#2242c7` |
| blue with a hint of purple |  `#533cc6` |
| booger |  `#9bb53c` |
| bright sea green |  `#05ffa6` |
| dark green blue |  `#1f6357` |
| deep turquoise |  `#017374` |
| green teal |  `#0cb577` |
| strong pink |  `#ff0789` |
| bland |  `#afa88b` |
| deep aqua |  `#08787f` |
| lavender pink |  `#dd85d7` |
| light moss green |  `#a6c875` |
| light seafoam green |  `#a7ffb5` |
| olive yellow |  `#c2b709` |
| pig pink |  `#e78ea5` |
| deep lilac |  `#966ebd` |
| desert |  `#ccad60` |
| dusty lavender |  `#ac86a8` |
| purpley grey |  `#947e94` |
| purply |  `#983fb2` |
| candy pink |  `#ff63e9` |
| light pastel green |  `#b2fba5` |
| boring green |  `#63b365` |
| kiwi green |  `#8ee53f` |
| light grey green |  `#b7e1a1` |
| orange pink |  `#ff6f52` |
| tea green |  `#bdf8a3` |
| very light brown |  `#d3b683` |
| egg shell |  `#fffcc4` |
| eggplant purple |  `#430541` |
| powder pink |  `#ffb2d0` |
| reddish grey |  `#997570` |
| baby shit brown |  `#ad900d` |
| liliac |  `#c48efd` |
| stormy blue |  `#507b9c` |
| ugly brown |  `#7d7103` |
| custard |  `#fffd78` |
| darkish pink |  `#da467d` |
| deep brown |  `#410200` |
| greenish beige |  `#c9d179` |
| manilla |  `#fffa86` |
| off blue |  `#5684ae` |
| battleship grey |  `#6b7c85` |
| browny green |  `#6f6c0a` |
| bruise |  `#7e4071` |
| kelley green |  `#009337` |
| sickly yellow |  `#d0e429` |
| sunny yellow |  `#fff917` |
| azul |  `#1d5dec` |
| darkgreen |  `#054907` |
| green/yellow |  `#b5ce08` |
| lichen |  `#8fb67b` |
| light light green |  `#c8ffb0` |
| pale gold |  `#fdde6c` |
| sun yellow |  `#ffdf22` |
| tan green |  `#a9be70` |
| burple |  `#6832e3` |
| butterscotch |  `#fdb147` |
| toupe |  `#c7ac7d` |
| dark cream |  `#fff39a` |
| indian red |  `#850e04` |
| light lavendar |  `#efc0fe` |
| poison green |  `#40fd14` |
| baby puke green |  `#b6c406` |
| bright yellow green |  `#9dff00` |
| charcoal grey |  `#3c4142` |
| squash |  `#f2ab15` |
| cinnamon |  `#ac4f06` |
| light pea green |  `#c4fe82` |
| radioactive green |  `#2cfa1f` |
| raw sienna |  `#9a6200` |
| baby purple |  `#ca9bf7` |
| cocoa |  `#875f42` |
| light royal blue |  `#3a2efe` |
| orangeish |  `#fd8d49` |
| rust brown |  `#8b3103` |
| sand brown |  `#cba560` |
| swamp |  `#698339` |
| tealish green |  `#0cdc73` |
| burnt siena |  `#b75203` |
| camo |  `#7f8f4e` |
| dusk blue |  `#26538d` |
| fern |  `#63a950` |
| old rose |  `#c87f89` |
| pale light green |  `#b1fc99` |
| peachy pink |  `#ff9a8a` |
| rosy pink |  `#f6688e` |
| light bluish green |  `#76fda8` |
| light bright green |  `#53fe5c` |
| light neon green |  `#4efd54` |
| light seafoam |  `#a0febf` |
| tiffany blue |  `#7bf2da` |
| washed out green |  `#bcf5a6` |
| browny orange |  `#ca6b02` |
| nice blue |  `#107ab0` |
| sapphire |  `#2138ab` |
| greyish teal |  `#719f91` |
| orangey yellow |  `#fdb915` |
| parchment |  `#fefcaf` |
| straw |  `#fcf679` |
| very dark brown |  `#1d0200` |
| terracota |  `#cb6843` |
| ugly blue |  `#31668a` |
| clear blue |  `#247afd` |
| creme |  `#ffffb6` |
| foam green |  `#90fda9` |
| grey/green |  `#86a17d` |
| light gold |  `#fddc5c` |
| seafoam blue |  `#78d1b6` |
| topaz |  `#13bbaf` |
| violet pink |  `#fb5ffc` |
| wintergreen |  `#20f986` |
| yellow tan |  `#ffe36e` |
| dark fuchsia |  `#9d0759` |
| indigo blue |  `#3a18b1` |
| light yellowish green |  `#c2ff89` |
| pale magenta |  `#d767ad` |
| rich purple |  `#720058` |
| sunflower yellow |  `#ffda03` |
| green/blue |  `#01c08d` |
| leather |  `#ac7434` |
| racing green |  `#014600` |
| vivid purple |  `#9900fa` |
| dark royal blue |  `#02066f` |
| hazel |  `#8e7618` |
| muted pink |  `#d1768f` |
| booger green |  `#96b403` |
| canary |  `#fdff63` |
| cool grey |  `#95a3a6` |
| dark taupe |  `#7f684e` |
| darkish purple |  `#751973` |
| true green |  `#089404` |
| coral pink |  `#ff6163` |
| dark sage |  `#598556` |
| dark slate blue |  `#214761` |
| flat blue |  `#3c73a8` |
| mushroom |  `#ba9e88` |
| rich blue |  `#021bf9` |
| dirty purple |  `#734a65` |
| greenblue |  `#23c48b` |
| icky green |  `#8fae22` |
| light khaki |  `#e6f2a2` |
| warm blue |  `#4b57db` |
| dark hot pink |  `#d90166` |
| deep sea blue |  `#015482` |
| carmine |  `#9d0216` |
| dark yellow green |  `#728f02` |
| pale peach |  `#ffe5ad` |
| plum purple |  `#4e0550` |
| golden rod |  `#f9bc08` |
| neon red |  `#ff073a` |
| old pink |  `#c77986` |
| very pale blue |  `#d6fffe` |
| blood orange |  `#fe4b03` |
| grapefruit |  `#fd5956` |
| sand yellow |  `#fce166` |
| clay brown |  `#b2713d` |
| dark blue grey |  `#1f3b4d` |
| flat green |  `#699d4c` |
| light green blue |  `#56fca2` |
| warm pink |  `#fb5581` |
| dodger blue |  `#3e82fc` |
| gross green |  `#a0bf16` |
| ice |  `#d6fffa` |
| metallic blue |  `#4f738e` |
| pale salmon |  `#ffb19a` |
| sap green |  `#5c8b15` |
| algae |  `#54ac68` |
| bluey grey |  `#89a0b0` |
| greeny grey |  `#7ea07a` |
| highlighter green |  `#1bfc06` |
| light light blue |  `#cafffb` |
| light mint |  `#b6ffbb` |
| raw umber |  `#a75e09` |
| vivid blue |  `#152eff` |
| deep lavender |  `#8d5eb7` |
| dull teal |  `#5f9e8f` |
| light greenish blue |  `#63f7b4` |
| mud green |  `#606602` |
| pinky |  `#fc86aa` |
| red wine |  `#8c0034` |
| shit green |  `#758000` |
| tan brown |  `#ab7e4c` |
| darkblue |  `#030764` |
| rosa |  `#fe86a4` |
| lipstick |  `#d5174e` |
| pale mauve |  `#fed0fc` |
| claret |  `#680018` |
| dandelion |  `#fedf08` |
| orangered |  `#fe420f` |
| poop green |  `#6f7c00` |
| ruby |  `#ca0147` |
| dark |  `#1b2431` |
| greenish turquoise |  `#00fbb0` |
| pastel red |  `#db5856` |
| piss yellow |  `#ddd618` |
| bright cyan |  `#41fdfe` |
| dark coral |  `#cf524e` |
| algae green |  `#21c36f` |
| darkish red |  `#a90308` |
| reddy brown |  `#6e1005` |
| blush pink |  `#fe828c` |
| camouflage green |  `#4b6113` |
| lawn green |  `#4da409` |
| putty |  `#beae8a` |
| vibrant blue |  `#0339f8` |
| dark sand |  `#a88f59` |
| purple/blue |  `#5d21d0` |
| saffron |  `#feb209` |
| twilight |  `#4e518b` |
| warm brown |  `#964e02` |
| bluegrey |  `#85a3b2` |
| bubble gum pink |  `#ff69af` |
| duck egg blue |  `#c3fbf4` |
| greenish cyan |  `#2afeb7` |
| petrol |  `#005f6a` |
| royal |  `#0c1793` |
| butter |  `#ffff81` |
| dusty orange |  `#f0833a` |
| off yellow |  `#f1f33f` |
| pale olive green |  `#b1d27b` |
| orangish |  `#fc824a` |
| leaf |  `#71aa34` |
| light blue grey |  `#b7c9e2` |
| dried blood |  `#4b0101` |
| lightish purple |  `#a552e6` |
| rusty red |  `#af2f0d` |
| lavender blue |  `#8b88f8` |
| light grass green |  `#9af764` |
| light mint green |  `#a6fbb2` |
| sunflower |  `#ffc512` |
| velvet |  `#750851` |
| brick orange |  `#c14a09` |
| lightish red |  `#fe2f4a` |
| pure blue |  `#0203e2` |
| twilight blue |  `#0a437a` |
| violet red |  `#a50055` |
| yellowy brown |  `#ae8b0c` |
| carnation |  `#fd798f` |
| muddy yellow |  `#bfac05` |
| dark seafoam green |  `#3eaf76` |
| deep rose |  `#c74767` |
| dusty red |  `#b9484e` |
| grey/blue |  `#647d8e` |
| lemon lime |  `#bffe28` |
| purple/pink |  `#d725de` |
| brown yellow |  `#b29705` |
| purple brown |  `#673a3f` |
| wisteria |  `#a87dc2` |
| banana yellow |  `#fafe4b` |
| lipstick red |  `#c0022f` |
| water blue |  `#0e87cc` |
| brown grey |  `#8d8468` |
| vibrant purple |  `#ad03de` |
| baby green |  `#8cff9e` |
| barf green |  `#94ac02` |
| eggshell blue |  `#c4fff7` |
| sandy yellow |  `#fdee73` |
| cool green |  `#33b864` |
| pale |  `#fff9d0` |
| blue/grey |  `#758da3` |
| hot magenta |  `#f504c9` |
| greyblue |  `#77a1b5` |
| purpley |  `#8756e4` |
| baby shit green |  `#889717` |
| brownish pink |  `#c27e79` |
| dark aquamarine |  `#017371` |
| diarrhea |  `#9f8303` |
| light mustard |  `#f7d560` |
| pale sky blue |  `#bdf6fe` |
| turtle green |  `#75b84f` |
| bright olive |  `#9cbb04` |
| dark grey blue |  `#29465b` |
| greeny brown |  `#696006` |
| lemon green |  `#adf802` |
| light periwinkle |  `#c1c6fc` |
| seaweed green |  `#35ad6b` |
| sunshine yellow |  `#fffd37` |
| ugly purple |  `#a442a0` |
| medium pink |  `#f36196` |
| puke brown |  `#947706` |
| very light pink |  `#fff4f2` |
| viridian |  `#1e9167` |
| bile |  `#b5c306` |
| faded yellow |  `#feff7f` |
| very pale green |  `#cffdbc` |
| vibrant green |  `#0add08` |
| bright lime |  `#87fd05` |
| spearmint |  `#1ef876` |
| light aquamarine |  `#7bfdc7` |
| light sage |  `#bcecac` |
| yellowgreen |  `#bbf90f` |
| baby poo |  `#ab9004` |
| dark seafoam |  `#1fb57a` |
| deep teal |  `#00555a` |
| heather |  `#a484ac` |
| rust orange |  `#c45508` |
| dirty blue |  `#3f829d` |
| fern green |  `#548d44` |
| bright lilac |  `#c95efb` |
| weird green |  `#3ae57f` |
| peacock blue |  `#016795` |
| avocado green |  `#87a922` |
| faded orange |  `#f0944d` |
| grape purple |  `#5d1451` |
| hot green |  `#25ff29` |
| lime yellow |  `#d0fe1d` |
| mango |  `#ffa62b` |
| shamrock |  `#01b44c` |
| bubblegum |  `#ff6cb5` |
| purplish brown |  `#6b4247` |
| vomit yellow |  `#c7c10c` |
| pale cyan |  `#b7fffa` |
| key lime |  `#aeff6e` |
| tomato red |  `#ec2d01` |
| lightgreen |  `#76ff7b` |
| merlot |  `#730039` |
| night blue |  `#040348` |
| purpleish pink |  `#df4ec8` |
| apple |  `#6ecb3c` |
| baby poop green |  `#8f9805` |
| green apple |  `#5edc1f` |
| heliotrope |  `#d94ff5` |
| yellow/green |  `#c8fd3d` |
| almost black |  `#070d0d` |
| cool blue |  `#4984b8` |
| leafy green |  `#51b73b` |
| mustard brown |  `#ac7e04` |
| dusk |  `#4e5481` |
| dull brown |  `#876e4b` |
| frog green |  `#58bc08` |
| vivid green |  `#2fef10` |
| bright light green |  `#2dfe54` |
| fluro green |  `#0aff02` |
| kiwi |  `#9cef43` |
| seaweed |  `#18d17b` |
| navy green |  `#35530a` |
| ultramarine blue |  `#1805db` |
| iris |  `#6258c4` |
| pastel orange |  `#ff964f` |
| yellowish orange |  `#ffab0f` |
| perrywinkle |  `#8f8ce7` |
| tealish |  `#24bca8` |
| dark plum |  `#3f012c` |
| pear |  `#cbf85f` |
| pinkish orange |  `#ff724c` |
| midnight purple |  `#280137` |
| light urple |  `#b36ff6` |
| dark mint |  `#48c072` |
| greenish tan |  `#bccb7a` |
| light burgundy |  `#a8415b` |
| turquoise blue |  `#06b1c4` |
| ugly pink |  `#cd7584` |
| sandy |  `#f1da7a` |
| electric pink |  `#ff0490` |
| muted purple |  `#805b87` |
| mid green |  `#50a747` |
| greyish |  `#a8a495` |
| neon yellow |  `#cfff04` |
| banana |  `#ffff7e` |
| carnation pink |  `#ff7fa7` |
| tomato |  `#ef4026` |
| sea |  `#3c9992` |
| muddy brown |  `#886806` |
| turquoise green |  `#04f489` |
| buff |  `#fef69e` |
| fawn |  `#cfaf7b` |
| muted blue |  `#3b719f` |
| pale rose |  `#fdc1c5` |
| dark mint green |  `#20c073` |
| amethyst |  `#9b5fc0` |
| blue/green |  `#0f9b8e` |
| chestnut |  `#742802` |
| sick green |  `#9db92c` |
| pea |  `#a4bf20` |
| rusty orange |  `#cd5909` |
| stone |  `#ada587` |
| rose red |  `#be013c` |
| pale aqua |  `#b8ffeb` |
| deep orange |  `#dc4d01` |
| earth |  `#a2653e` |
| mossy green |  `#638b27` |
| grassy green |  `#419c03` |
| pale lime green |  `#b1ff65` |
| light grey blue |  `#9dbcd4` |
| pale grey |  `#fdfdfe` |
| asparagus |  `#77ab56` |
| blueberry |  `#464196` |
| purple red |  `#990147` |
| pale lime |  `#befd73` |
| greenish teal |  `#32bf84` |
| caramel |  `#af6f09` |
| deep magenta |  `#a0025c` |
| light peach |  `#ffd8b1` |
| milk chocolate |  `#7f4e1e` |
| ocher |  `#bf9b0c` |
| off green |  `#6ba353` |
| purply pink |  `#f075e6` |
| lightblue |  `#7bc8f6` |
| dusky blue |  `#475f94` |
| golden |  `#f5bf03` |
| light beige |  `#fffeb6` |
| butter yellow |  `#fffd74` |
| dusky purple |  `#895b7b` |
| french blue |  `#436bad` |
| ugly yellow |  `#d0c101` |
| greeny yellow |  `#c6f808` |
| orangish red |  `#f43605` |
| shamrock green |  `#02c14d` |
| orangish brown |  `#b25f03` |
| tree green |  `#2a7e19` |
| deep violet |  `#490648` |
| gunmetal |  `#536267` |
| blue/purple |  `#5a06ef` |
| cherry |  `#cf0234` |
| sandy brown |  `#c4a661` |
| warm grey |  `#978a84` |
| dark indigo |  `#1f0954` |
| midnight |  `#03012d` |
| bluey green |  `#2bb179` |
| grey pink |  `#c3909b` |
| soft purple |  `#a66fb5` |
| blood |  `#770001` |
| brown red |  `#922b05` |
| medium grey |  `#7d7f7c` |
| berry |  `#990f4b` |
| poo |  `#8f7303` |
| purpley pink |  `#c83cb9` |
| light salmon |  `#fea993` |
| snot |  `#acbb0d` |
| easter purple |  `#c071fe` |
| light yellow green |  `#ccfd7f` |
| dark navy blue |  `#00022e` |
| drab |  `#828344` |
| light rose |  `#ffc5cb` |
| rouge |  `#ab1239` |
| purplish red |  `#b0054b` |
| slime green |  `#99cc04` |
| baby poop |  `#937c00` |
| irish green |  `#019529` |
| pink/purple |  `#ef1de7` |
| dark navy |  `#000435` |
| greeny blue |  `#42b395` |
| light plum |  `#9d5783` |
| pinkish grey |  `#c8aca9` |
| dirty orange |  `#c87606` |
| rust red |  `#aa2704` |
| pale lilac |  `#e4cbff` |
| orangey red |  `#fa4224` |
| primary blue |  `#0804f9` |
| kermit green |  `#5cb200` |
| brownish purple |  `#76424e` |
| murky green |  `#6c7a0e` |
| wheat |  `#fbdd7e` |
| very dark purple |  `#2a0134` |
| bottle green |  `#044a05` |
| watermelon |  `#fd4659` |
| deep sky blue |  `#0d75f8` |
| fire engine red |  `#fe0002` |
| yellow ochre |  `#cb9d06` |
| pumpkin orange |  `#fb7d07` |
| pale olive |  `#b9cc81` |
| light lilac |  `#edc8ff` |
| lightish green |  `#61e160` |
| carolina blue |  `#8ab8fe` |
| mulberry |  `#920a4e` |
| shocking pink |  `#fe02a2` |
| auburn |  `#9a3001` |
| bright lime green |  `#65fe08` |
| celadon |  `#befdb7` |
| pinkish brown |  `#b17261` |
| poo brown |  `#885f01` |
| bright sky blue |  `#02ccfe` |
| celery |  `#c1fd95` |
| dirt brown |  `#836539` |
| strawberry |  `#fb2943` |
| dark lime |  `#84b701` |
| copper |  `#b66325` |
| medium brown |  `#7f5112` |
| muted green |  `#5fa052` |
| robin's egg |  `#6dedfd` |
| bright aqua |  `#0bf9ea` |
| bright lavender |  `#c760ff` |
| ivory |  `#ffffcb` |
| very light purple |  `#f6cefc` |
| light navy |  `#155084` |
| pink red |  `#f5054f` |
| olive brown |  `#645403` |
| poop brown |  `#7a5901` |
| mustard green |  `#a8b504` |
| ocean green |  `#3d9973` |
| very dark blue |  `#000133` |
| dusty green |  `#76a973` |
| light navy blue |  `#2e5a88` |
| minty green |  `#0bf77d` |
| adobe |  `#bd6c48` |
| barney |  `#ac1db8` |
| jade green |  `#2baf6a` |
| bright light blue |  `#26f7fd` |
| light lime |  `#aefd6c` |
| dark khaki |  `#9b8f55` |
| orange yellow |  `#ffad01` |
| ocre |  `#c69c04` |
| maize |  `#f4d054` |
| faded pink |  `#de9dac` |
| british racing green |  `#05480d` |
| sandstone |  `#c9ae74` |
| mud brown |  `#60460f` |
| light sea green |  `#98f6b0` |
| robin egg blue |  `#8af1fe` |
| aqua marine |  `#2ee8bb` |
| dark sea green |  `#11875d` |
| soft pink |  `#fdb0c0` |
| orangey brown |  `#b16002` |
| cherry red |  `#f7022a` |
| burnt yellow |  `#d5ab09` |
| brownish grey |  `#86775f` |
| camel |  `#c69f59` |
| purplish grey |  `#7a687f` |
| marine |  `#042e60` |
| greyish pink |  `#c88d94` |
| pale turquoise |  `#a5fbd5` |
| pastel yellow |  `#fffe71` |
| bluey purple |  `#6241c7` |
| canary yellow |  `#fffe40` |
| faded red |  `#d3494e` |
| sepia |  `#985e2b` |
| coffee |  `#a6814c` |
| bright magenta |  `#ff08e8` |
| mocha |  `#9d7651` |
| ecru |  `#feffca` |
| purpleish |  `#98568d` |
| cranberry |  `#9e003a` |
| darkish green |  `#287c37` |
| brown orange |  `#b96902` |
| dusky rose |  `#ba6873` |
| melon |  `#ff7855` |
| sickly green |  `#94b21c` |
| silver |  `#c5c9c7` |
| purply blue |  `#661aee` |
| purpleish blue |  `#6140ef` |
| hospital green |  `#9be5aa` |
| shit brown |  `#7b5804` |
| mid blue |  `#276ab3` |
| amber |  `#feb308` |
| easter green |  `#8cfd7e` |
| soft blue |  `#6488ea` |
| cerulean blue |  `#056eee` |
| golden brown |  `#b27a01` |
| bright turquoise |  `#0ffef9` |
| red pink |  `#fa2a55` |
| red purple |  `#820747` |
| greyish brown |  `#7a6a4f` |
| vermillion |  `#f4320c` |
| russet |  `#a13905` |
| steel grey |  `#6f828a` |
| lighter purple |  `#a55af4` |
| bright violet |  `#ad0afd` |
| prussian blue |  `#004577` |
| slate green |  `#658d6d` |
| dirty pink |  `#ca7b80` |
| dark blue green |  `#005249` |
| pine |  `#2b5d34` |
| yellowy green |  `#bff128` |
| dark gold |  `#b59410` |
| bluish |  `#2976bb` |
| darkish blue |  `#014182` |
| dull red |  `#bb3f3f` |
| pinky red |  `#fc2647` |
| bronze |  `#a87900` |
| pale teal |  `#82cbb2` |
| military green |  `#667c3e` |
| barbie pink |  `#fe46a5` |
| bubblegum pink |  `#fe83cc` |
| pea soup green |  `#94a617` |
| dark mustard |  `#a88905` |
| shit |  `#7f5f00` |
| medium purple |  `#9e43a2` |
| very dark green |  `#062e03` |
| dirt |  `#8a6e45` |
| dusky pink |  `#cc7a8b` |
| red violet |  `#9e0168` |
| lemon yellow |  `#fdff38` |
| pistachio |  `#c0fa8b` |
| dull yellow |  `#eedc5b` |
| dark lime green |  `#7ebd01` |
| denim blue |  `#3b5b92` |
| teal blue |  `#01889f` |
| lightish blue |  `#3d7afd` |
| purpley blue |  `#5f34e7` |
| light indigo |  `#6d5acf` |
| swamp green |  `#748500` |
| brown green |  `#706c11` |
| dark maroon |  `#3c0008` |
| hot purple |  `#cb00f5` |
| dark forest green |  `#002d04` |
| faded blue |  `#658cbb` |
| drab green |  `#749551` |
| light lime green |  `#b9ff66` |
| snot green |  `#9dc100` |
| yellowish |  `#faee66` |
| light blue green |  `#7efbb3` |
| bordeaux |  `#7b002c` |
| light mauve |  `#c292a1` |
| ocean |  `#017b92` |
| marigold |  `#fcc006` |
| muddy green |  `#657432` |
| dull orange |  `#d8863b` |
| steel |  `#738595` |
| electric purple |  `#aa23ff` |
| fluorescent green |  `#08ff08` |
| yellowish brown |  `#9b7a01` |
| blush |  `#f29e8e` |
| soft green |  `#6fc276` |
| bright orange |  `#ff5b00` |
| lemon |  `#fdff52` |
| purple grey |  `#866f85` |
| acid green |  `#8ffe09` |
| pale lavender |  `#eecffe` |
| violet blue |  `#510ac9` |
| light forest green |  `#4f9153` |
| burnt red |  `#9f2305` |
| khaki green |  `#728639` |
| cerise |  `#de0c62` |
| faded purple |  `#916e99` |
| apricot |  `#ffb16d` |
| dark olive green |  `#3c4d03` |
| grey brown |  `#7f7053` |
| green grey |  `#77926f` |
| true blue |  `#010fcc` |
| pale violet |  `#ceaefa` |
| periwinkle blue |  `#8f99fb` |
| light sky blue |  `#c6fcff` |
| blurple |  `#5539cc` |
| green brown |  `#544e03` |
| bluegreen |  `#017a79` |
| bright teal |  `#01f9c6` |
| brownish yellow |  `#c9b003` |
| pea soup |  `#929901` |
| forest |  `#0b5509` |
| barney purple |  `#a00498` |
| ultramarine |  `#2000b1` |
| purplish |  `#94568c` |
| puke yellow |  `#c2be0e` |
| bluish grey |  `#748b97` |
| dark periwinkle |  `#665fd1` |
| dark lilac |  `#9c6da5` |
| reddish |  `#c44240` |
| light maroon |  `#a24857` |
| dusty purple |  `#825f87` |
| terra cotta |  `#c9643b` |
| avocado |  `#90b134` |
| marine blue |  `#01386a` |
| teal green |  `#25a36f` |
| slate grey |  `#59656d` |
| lighter green |  `#75fd63` |
| electric green |  `#21fc0d` |
| dusty blue |  `#5a86ad` |
| golden yellow |  `#fec615` |
| bright yellow |  `#fffd01` |
| light lavender |  `#dfc5fe` |
| umber |  `#b26400` |
| poop |  `#7f5e00` |
| dark peach |  `#de7e5d` |
| jungle green |  `#048243` |
| eggshell |  `#ffffd4` |
| denim |  `#3b638c` |
| yellow brown |  `#b79400` |
| dull purple |  `#84597e` |
| chocolate brown |  `#411900` |
| wine red |  `#7b0323` |
| neon blue |  `#04d9ff` |
| dirty green |  `#667e2c` |
| light tan |  `#fbeeac` |
| ice blue |  `#d7fffe` |
| cadet blue |  `#4e7496` |
| dark mauve |  `#874c62` |
| very light blue |  `#d5ffff` |
| grey purple |  `#826d8c` |
| pastel pink |  `#ffbacd` |
| very light green |  `#d1ffbd` |
| dark sky blue |  `#448ee4` |
| evergreen |  `#05472a` |
| dull pink |  `#d5869d` |
| aubergine |  `#3d0734` |
| mahogany |  `#4a0100` |
| reddish orange |  `#f8481c` |
| deep green |  `#02590f` |
| vomit green |  `#89a203` |
| purple pink |  `#e03fd8` |
| dusty pink |  `#d58a94` |
| faded green |  `#7bb274` |
| camo green |  `#526525` |
| pinky purple |  `#c94cbe` |
| pink purple |  `#db4bda` |
| brownish red |  `#9e3623` |
| dark rose |  `#b5485d` |
| mud |  `#735c12` |
| brownish |  `#9c6d57` |
| emerald green |  `#028f1e` |
| pale brown |  `#b1916e` |
| dull blue |  `#49759c` |
| burnt umber |  `#a0450e` |
| medium green |  `#39ad48` |
| clay |  `#b66a50` |
| light aqua |  `#8cffdb` |
| light olive green |  `#a4be5c` |
| brownish orange |  `#cb7723` |
| dark aqua |  `#05696b` |
| purplish pink |  `#ce5dae` |
| dark salmon |  `#c85a53` |
| greenish grey |  `#96ae8d` |
| jade |  `#1fa774` |
| ugly green |  `#7a9703` |
| dark beige |  `#ac9362` |
| emerald |  `#01a049` |
| pale red |  `#d9544d` |
| light magenta |  `#fa5ff7` |
| sky |  `#82cafc` |
| light cyan |  `#acfffc` |
| yellow orange |  `#fcb001` |
| reddish purple |  `#910951` |
| reddish pink |  `#fe2c54` |
| orchid |  `#c875c4` |
| dirty yellow |  `#cdc50a` |
| orange red |  `#fd411e` |
| deep red |  `#9a0200` |
| orange brown |  `#be6400` |
| cobalt blue |  `#030aa7` |
| neon pink |  `#fe019a` |
| rose pink |  `#f7879a` |
| greyish purple |  `#887191` |
| raspberry |  `#b00149` |
| aqua green |  `#12e193` |
| salmon pink |  `#fe7b7c` |
| tangerine |  `#ff9408` |
| brownish green |  `#6a6e09` |
| red brown |  `#8b2e16` |
| greenish brown |  `#696112` |
| pumpkin |  `#e17701` |
| pine green |  `#0a481e` |
| charcoal |  `#343837` |
| baby pink |  `#ffb7ce` |
| cornflower |  `#6a79f7` |
| blue violet |  `#5d06e9` |
| chocolate |  `#3d1c02` |
| greyish green |  `#82a67d` |
| scarlet |  `#be0119` |
| green yellow |  `#c9ff27` |
| dark olive |  `#373e02` |
| sienna |  `#a9561e` |
| pastel purple |  `#caa0ff` |
| terracotta |  `#ca6641` |
| aqua blue |  `#02d8e9` |
| sage green |  `#88b378` |
| blood red |  `#980002` |
| deep pink |  `#cb0162` |
| grass |  `#5cac2d` |
| moss |  `#769958` |
| pastel blue |  `#a2bffe` |
| bluish green |  `#10a674` |
| green blue |  `#06b48b` |
| dark tan |  `#af884a` |
| greenish blue |  `#0b8b87` |
| pale orange |  `#ffa756` |
| vomit |  `#a2a415` |
| forrest green |  `#154406` |
| dark lavender |  `#856798` |
| dark violet |  `#34013f` |
| purple blue |  `#632de9` |
| dark cyan |  `#0a888a` |
| olive drab |  `#6f7632` |
| pinkish |  `#d46a7e` |
| cobalt |  `#1e488f` |
| neon purple |  `#bc13fe` |
| light turquoise |  `#7ef4cc` |
| apple green |  `#76cd26` |
| dull green |  `#74a662` |
| wine |  `#80013f` |
| powder blue |  `#b1d1fc` |
| off white |  `#ffffe4` |
| electric blue |  `#0652ff` |
| dark turquoise |  `#045c5a` |
| blue purple |  `#5729ce` |
| azure |  `#069af3` |
| bright red |  `#ff000d` |
| pinkish red |  `#f10c45` |
| cornflower blue |  `#5170d7` |
| light olive |  `#acbf69` |
| grape |  `#6c3461` |
| greyish blue |  `#5e819d` |
| purplish blue |  `#601ef9` |
| yellowish green |  `#b0dd16` |
| greenish yellow |  `#cdfd02` |
| medium blue |  `#2c6fbb` |
| dusty rose |  `#c0737a` |
| light violet |  `#d6b4fc` |
| midnight blue |  `#020035` |
| bluish purple |  `#703be7` |
| red orange |  `#fd3c06` |
| dark magenta |  `#960056` |
| greenish |  `#40a368` |
| ocean blue |  `#03719c` |
| coral |  `#fc5a50` |
| cream |  `#ffffc2` |
| reddish brown |  `#7f2b0a` |
| burnt sienna |  `#b04e0f` |
| brick |  `#a03623` |
| sage |  `#87ae73` |
| grey green |  `#789b73` |
| white |  `#ffffff` |
| robin's egg blue |  `#98eff9` |
| moss green |  `#658b38` |
| steel blue |  `#5a7d9a` |
| eggplant |  `#380835` |
| light yellow |  `#fffe7a` |
| leaf green |  `#5ca904` |
| light grey |  `#d8dcd6` |
| puke |  `#a5a502` |
| pinkish purple |  `#d648d7` |
| sea blue |  `#047495` |
| pale purple |  `#b790d4` |
| slate blue |  `#5b7c99` |
| blue grey |  `#607c8e` |
| hunter green |  `#0b4008` |
| fuchsia |  `#ed0dd9` |
| crimson |  `#8c000f` |
| pale yellow |  `#ffff84` |
| ochre |  `#bf9005` |
| mustard yellow |  `#d2bd0a` |
| light red |  `#ff474c` |
| cerulean |  `#0485d1` |
| pale pink |  `#ffcfdc` |
| deep blue |  `#040273` |
| rust |  `#a83c09` |
| light teal |  `#90e4c1` |
| slate |  `#516572` |
| goldenrod |  `#fac205` |
| dark yellow |  `#d5b60a` |
| dark grey |  `#363737` |
| army green |  `#4b5d16` |
| grey blue |  `#6b8ba4` |
| seafoam |  `#80f9ad` |
| puce |  `#a57e52` |
| spring green |  `#a9f971` |
| dark orange |  `#c65102` |
| sand |  `#e2ca76` |
| pastel green |  `#b0ff9d` |
| mint |  `#9ffeb0` |
| light orange |  `#fdaa48` |
| bright pink |  `#fe01b1` |
| chartreuse |  `#c1f80a` |
| deep purple |  `#36013f` |
| dark brown |  `#341c02` |
| taupe |  `#b9a281` |
| pea green |  `#8eab12` |
| puke green |  `#9aae07` |
| kelly green |  `#02ab2e` |
| seafoam green |  `#7af9ab` |
| blue green |  `#137e6d` |
| khaki |  `#aaa662` |
| burgundy |  `#610023` |
| dark teal |  `#014d4e` |
| brick red |  `#8f1402` |
| royal purple |  `#4b006e` |
| plum |  `#580f41` |
| mint green |  `#8fff9f` |
| gold |  `#dbb40c` |
| baby blue |  `#a2cffe` |
| yellow green |  `#c0fb2d` |
| bright purple |  `#be03fd` |
| dark red |  `#840000` |
| pale blue |  `#d0fefe` |
| grass green |  `#3f9b0b` |
| navy |  `#01153e` |
| aquamarine |  `#04d8b2` |
| burnt orange |  `#c04e01` |
| neon green |  `#0cff0c` |
| bright blue |  `#0165fc` |
| rose |  `#cf6275` |
| light pink |  `#ffd1df` |
| mustard |  `#ceb301` |
| indigo |  `#380282` |
| lime |  `#aaff32` |
| sea green |  `#53fca1` |
| periwinkle |  `#8e82fe` |
| dark pink |  `#cb416b` |
| olive green |  `#677a04` |
| peach |  `#ffb07c` |
| pale green |  `#c7fdb5` |
| light brown |  `#ad8150` |
| hot pink |  `#ff028d` |
| black |  `#000000` |
| lilac |  `#cea2fd` |
| navy blue |  `#001146` |
| royal blue |  `#0504aa` |
| beige |  `#e6daa6` |
| salmon |  `#ff796c` |
| olive |  `#6e750e` |
| maroon |  `#650021` |
| bright green |  `#01ff07` |
| dark purple |  `#35063e` |
| mauve |  `#ae7181` |
| forest green |  `#06470c` |
| aqua |  `#13eac9` |
| cyan |  `#00ffff` |
| tan |  `#d1b26f` |
| dark blue |  `#00035b` |
| lavender |  `#c79fef` |
| turquoise |  `#06c2ac` |
| dark green |  `#033500` |
| violet |  `#9a0eea` |
| light purple |  `#bf77f6` |
| lime green |  `#89fe05` |
| grey |  `#929591` |
| sky blue |  `#75bbfd` |
| yellow |  `#ffff14` |
| magenta |  `#c20078` |
| light green |  `#96f97b` |
| orange |  `#f97306` |
| teal |  `#029386` |
| light blue |  `#95d0fc` |
| red |  `#e50000` |
| brown |  `#653700` |
| pink |  `#ff81c0` |
| blue |  `#0343df` |
| green |  `#15b01a` |
| purple |  `#7e1e9c` |
To force use xkcd color, use `xkcd:` (ie. `xkcd:light olive green`).
***
### CSS4 Colors:
| Color Name | Hex Code |
| -------------------- | ------------------------------------------------------------------------- |
| aliceblue |  `#F0F8FF` |
| antiquewhite |  `#FAEBD7` |
| aqua |  `#00FFFF` |
| aquamarine |  `#7FFFD4` |
| azure |  `#F0FFFF` |
| beige |  `#F5F5DC` |
| bisque |  `#FFE4C4` |
| black |  `#000000` |
| blanchedalmond |  `#FFEBCD` |
| blue |  `#0000FF` |
| blueviolet |  `#8A2BE2` |
| brown |  `#A52A2A` |
| burlywood |  `#DEB887` |
| cadetblue |  `#5F9EA0` |
| chartreuse |  `#7FFF00` |
| chocolate |  `#D2691E` |
| coral |  `#FF7F50` |
| cornflowerblue |  `#6495ED` |
| cornsilk |  `#FFF8DC` |
| crimson |  `#DC143C` |
| cyan |  `#00FFFF` |
| darkblue |  `#00008B` |
| darkcyan |  `#008B8B` |
| darkgoldenrod |  `#B8860B` |
| darkgray |  `#A9A9A9` |
| darkgreen |  `#006400` |
| darkgrey |  `#A9A9A9` |
| darkkhaki |  `#BDB76B` |
| darkmagenta |  `#8B008B` |
| darkolivegreen |  `#556B2F` |
| darkorange |  `#FF8C00` |
| darkorchid |  `#9932CC` |
| darkred |  `#8B0000` |
| darksalmon |  `#E9967A` |
| darkseagreen |  `#8FBC8F` |
| darkslateblue |  `#483D8B` |
| darkslategray |  `#2F4F4F` |
| darkslategrey |  `#2F4F4F` |
| darkturquoise |  `#00CED1` |
| darkviolet |  `#9400D3` |
| deeppink |  `#FF1493` |
| deepskyblue |  `#00BFFF` |
| dimgray |  `#696969` |
| dimgrey |  `#696969` |
| dodgerblue |  `#1E90FF` |
| firebrick |  `#B22222` |
| floralwhite |  `#FFFAF0` |
| forestgreen |  `#228B22` |
| fuchsia |  `#FF00FF` |
| gainsboro |  `#DCDCDC` |
| ghostwhite |  `#F8F8FF` |
| gold |  `#FFD700` |
| goldenrod |  `#DAA520` |
| gray |  `#808080` |
| green |  `#008000` |
| greenyellow |  `#ADFF2F` |
| grey |  `#808080` |
| honeydew |  `#F0FFF0` |
| hotpink |  `#FF69B4` |
| indianred |  `#CD5C5C` |
| indigo |  `#4B0082` |
| ivory |  `#FFFFF0` |
| khaki |  `#F0E68C` |
| lavender |  `#E6E6FA` |
| lavenderblush |  `#FFF0F5` |
| lawngreen |  `#7CFC00` |
| lemonchiffon |  `#FFFACD` |
| lightblue |  `#ADD8E6` |
| lightcoral |  `#F08080` |
| lightcyan |  `#E0FFFF` |
| lightgoldenrodyellow |  `#FAFAD2` |
| lightgray |  `#D3D3D3` |
| lightgreen |  `#90EE90` |
| lightgrey |  `#D3D3D3` |
| lightpink |  `#FFB6C1` |
| lightsalmon |  `#FFA07A` |
| lightseagreen |  `#20B2AA` |
| lightskyblue |  `#87CEFA` |
| lightslategray |  `#778899` |
| lightslategrey |  `#778899` |
| lightsteelblue |  `#B0C4DE` |
| lightyellow |  `#FFFFE0` |
| lime |  `#00FF00` |
| limegreen |  `#32CD32` |
| linen |  `#FAF0E6` |
| magenta |  `#FF00FF` |
| maroon |  `#800000` |
| mediumaquamarine |  `#66CDAA` |
| mediumblue |  `#0000CD` |
| mediumorchid |  `#BA55D3` |
| mediumpurple |  `#9370DB` |
| mediumseagreen |  `#3CB371` |
| mediumslateblue |  `#7B68EE` |
| mediumspringgreen |  `#00FA9A` |
| mediumturquoise |  `#48D1CC` |
| mediumvioletred |  `#C71585` |
| midnightblue |  `#191970` |
| mintcream |  `#F5FFFA` |
| mistyrose |  `#FFE4E1` |
| moccasin |  `#FFE4B5` |
| navajowhite |  `#FFDEAD` |
| navy |  `#000080` |
| oldlace |  `#FDF5E6` |
| olive |  `#808000` |
| olivedrab |  `#6B8E23` |
| orange |  `#FFA500` |
| orangered |  `#FF4500` |
| orchid |  `#DA70D6` |
| palegoldenrod |  `#EEE8AA` |
| palegreen |  `#98FB98` |
| paleturquoise |  `#AFEEEE` |
| palevioletred |  `#DB7093` |
| papayawhip |  `#FFEFD5` |
| peachpuff |  `#FFDAB9` |
| peru |  `#CD853F` |
| pink |  `#FFC0CB` |
| plum |  `#DDA0DD` |
| powderblue |  `#B0E0E6` |
| purple |  `#800080` |
| rebeccapurple |  `#663399` |
| red |  `#FF0000` |
| rosybrown |  `#BC8F8F` |
| royalblue |  `#4169E1` |
| saddlebrown |  `#8B4513` |
| salmon |  `#FA8072` |
| sandybrown |  `#F4A460` |
| seagreen |  `#2E8B57` |
| seashell |  `#FFF5EE` |
| sienna |  `#A0522D` |
| silver |  `#C0C0C0` |
| skyblue |  `#87CEEB` |
| slateblue |  `#6A5ACD` |
| slategray |  `#708090` |
| slategrey |  `#708090` |
| snow |  `#FFFAFA` |
| springgreen |  `#00FF7F` |
| steelblue |  `#4682B4` |
| tan |  `#D2B48C` |
| teal |  `#008080` |
| thistle |  `#D8BFD8` |
| tomato |  `#FF6347` |
| turquoise |  `#40E0D0` |
| violet |  `#EE82EE` |
| wheat |  `#F5DEB3` |
| white |  `#FFFFFF` |
| whitesmoke |  `#F5F5F5` |
| yellow |  `#FFFF00` |
| yellowgreen |  `#9ACD32` |
To force use CSS4 color, use `css:` (ie. `css:thistle`).
***
## Note:
If no color group prefix is provided, the color name will be retrieved in the following order:
* Tableau
* XKCD
* CSS4
* Base
# Archived Documentation
Anything in this header exists as a place-holder to our origninal docs using the GitHub Wiki function.
They will eventually be adapted, updated, and moved elsewhere on this site. Do not expect links you copy today to remain valid into the future.
# Configure Modmail and Logviewer
## Log Viewer
To be able to store data such as logs, you will need to use your own database.
Modmail supports MongoDB, and you are required to provide a MongoDB connection URI to the bot. You can get a **free** 500MB cluster from [MongoDB Atlas](https://www.mongodb.com/cloud/atlas). (Enough to store 3 million messages)
Upon creating an account, you will be greeted with this page:
Select one of the servers marked with "FREE TIER AVAILABLE" for the free option and click on "Create Cluster".
 
Follow the "Getting Started" tutorial on the bottom left, by creating a database user, whitelisting your IP, and connect to the cluster. When whitelisting you IP, be sure to select ALLOW ACCESS FROM ANYWHERE since Heroku does not grant a fixed IP.
Your IP should look something like this, with `0.0.0.0/0`:
The last part is to generate a MongoDB URI, navigate to "Clusters" and click on "CONNECT" (as shown in "Getting Started"). From the popup, select the middle option "Connect Your Application", and then the first option "Short SRV connection string".  
This will show a URI under "Copy the SRV address:", copy that, and replace `` with the database user password (**not your account password**). The final URI should look something like this:
```
mongodb+srv://username:password@cluster0-abcde.mongodb.net/
```
If your URI is followed by `test?retryWrites=true` or anything else, don't include it.
## Deploying the Log Viewer
[](https://heroku.com/deploy?template=https://github.com/modmail-dev/logviewer)
You will also need to deploy another separate log viewer application from [this repo](https://github.com/kyb3r/logviewer). Click on the deploy button over there and fill in the configurations upon request. This is a **separate** Heroku application from the bot and is a simple website that will be used to display your thread logs.
## Modmail
Star the repository before you start 😉
[](https://heroku.com/deploy?template=https://github.com/modmail-dev/modmail)
1. Input a name of your choice for your app, the Heroku app name is not important.
2. Input your bot token into the `TOKEN` field.
3. Put the [ID of your Server](https://support.discordapp.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-) into the `GUILD_ID` field.
4. Put your own ID in the `OWNERS` field (if there are multiple owners, separate them by a comma: `123455,234567,456782`).
5. Input your MongoDB connection URI from the previous section into the `MONGO_URI` field.
6. Input the URL of your log viewer Heroku app (`https://yourlogviewerappname.herokuapp.com`) into the `LOG_URL` field.
7. Click the `deploy app` button and wait for it to finish.
8. Click `Manage App` and go into the `Resources` tab.
9. Now turn on the worker by clicking the pencil icon.
10. If you want, you can go over and check the application logs to see if everything is running smoothly.
11. Once the bot is online in your server, do `[your prefix]setup` (defaults `?`) and you are good to go!
Your bot is ready! Head over to Discord and try it out! If you have any issues, join the [Discord server](https://discord.gg/cnUpwrnpYb).
**Make sure to give the bot Manage Channels, Manage Messages and View Audit Logs permissions!**
# Frequently Asked Questions
> Last Updated: March 16, 2023
#### What is Modmail?
Modmail is a Discord bot, similar to Reddit's Modmail feature. It serves as a shared inbox for server staff to communicate with their users - and vice versa - in a seamless way.
#### Can I invite Modmail?
Unfortunately, due to the nature of the bot, there is not a global invite link. Nonetheless, you can obtain a free copy of Modmail for your server. Follow the official tutorial at . However, if you don’t want the hassle of installing and maintaining Modmail, we offer installation, hosting, and other cool perks for [Patrons](https://patreon.com/kyber).
#### How does Modmail work?
Modmail uses the Discord API to interact with the platform. When someone sends a DM to the bot, it will create a new thread. Members of the moderation team can help the user and once the conversation ended, you will have access to a beautiful log of it online.
#### Is Modmail safe?
Your Modmail bot is safe as long as you don't share your bot's token. If you share your token, a "hacker" can take control over your bot. If you shared your bot token by mistake, regenerate a new token via the Discord Developer Portal.
#### Where is my data stored?
All your data including settings, blocked users, logs, installed plugins etc. are stored in your MongoDB database. The bot files only contain the stuff needed to run the bot. This means you can move your bot to a different host and still have your data intact, as long as you use the same MongoDB URI.
#### Can I request new features?
Modmail is an open-source project, which means you can easily add or request new features. You can make an issue or submit a pull request to the development branch on the repository. [Check out the contribution guidelines.](https://github.com/modmail-dev/modmail/blob/master/CONTRIBUTING.md)
#### How do I become a support member?
To join our support team, join our [Discord server](https://discord.gg/cnUpwrnpYb). One of the more experienced members will hold an interview to check if you fit the requirements.
#### Can I add commands to the bot?
You can add commands to the bot using plugins. All currently approved plugins can be found in the `?plugin registry` command. You can also see [this page](https://github.com/modmail-dev/modmail/wiki/Unofficial-List-of-Plugins) for an unofficial list of plugins.
#### My bot is offline, what do I do?
Join our [Discord server](https://discord.gg/cnUpwrnpYb) and DM Modmail. One of our support members will assist you and help you fix the issue.
#### How can I donate the developers?
You can support the developers on the [Patreon page](https://patreon.com/kyber). You will also receive various rewards for it.
#### Does anyone get any info when I create my own modmail?
There is not much information we get about your instance of modmail, The only thing what we recieve is the guild-info, For example: The guildname, The amount of members of the guild, the botname, and the bot-owner. Using this we keep track of how many modmail-instances get created on a monthly/yearly base. ( Only modmail-developers can see this ) You can disable this by adding `DATA_COLLECTION=no`to your `.env`.
***
#### Answer not found?
Feel free to join our [Discord server](https://discord.gg/cnUpwrnpYb). People will gladly help you with any questions that you have!
