Create a Discord bot

The first step in setting up Modmail is to create a Discord bot. Head over to the Discord Developer Portal and create a new application.

Once you've created a new application, head over to the Bot tab and create a new bot.

Click Add bot to create the bot. After adding a bot, reset the token and copy and store the newly generated token in your Text editor for later use.

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.

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

https://discord.com/oauth2/authorize?scope=bot&permissions=416075476184&client_id=YOUR-ID-HERE

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.

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

Modmail uses MongoDB to store its internal configurations and log histories. You must create a MongoDB database in order to use Modmail.

You can use MongoDB Atlas (opens in a new tab) as they allow a free 512MB storage instance which is more than enough for Modmail, though it is also possible to self-host the database on your own machine, you may skip this step if you intend to self-host the database.

Head over to MongoDB Atlas (opens in a new tab) and register for a free account:

Once you've registered and 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. Choose the region that's closest to where you're hosting your bot. Make sure the Cluster Tier is set to M0 Sandbox and the price shows as FREE.

On the following Security Quickstart page, do the following:

1. Authentication method: Username and Password Username: `modmail` Password: Click **Autogenerate Secure Password** - don't type your own password!
2. Copy and save the password into your text editor, 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.

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.

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:

My bot token: MTA3Djv3IAxNjk1NDgdKD231.G1AoUjD.5z629aKP34JKHn4v1EsdNUwdDO3MvBR9ifVES4
My database password: elAO7wF1r07pNG6u
My MongoDB connection string: mongodb+srv://modmail:<password>@cluster0.example.mongodb.net/

Finally, you will need to combine the database password with the MongoDB connection string by replacing the <password> (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 at the end of this step:

My bot token: MTA3Djv3IAxNjk1NDgdKD231.G1AoUjD.5z629aKP34JKHn4v1EsdNUwdDO3MvBR9ifVES4
My MongoDB connection string: mongodb+srv://modmail:[email protected]

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 - [Optional] Logviewer URL that will be used to view threads in your web browser
• 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:

TOKEN=OTY3Nzy5MzU5NjAzMzU2NzE4.GtKp_5.JOTYRwGW-LB1He5widCu73vXtmi90KxsqkmoOg
LOG_URL=https://logs.mymodmailbot.com/
GUILD_ID=1079074933008781362
OWNERS=188363246695219201,231595246213922828
MONGO_URI=mongodb+srv://username:[email protected]/

Hosting Modmail

Your next step is to choose one the hosting method that's preferable to you. Each method has their pros and cons, be sure to take them into consideration when choosing your hosting platform to run Modmail.

For hosting on a personal device or VPS, refer to the "Installing Modmail" section as we cover some widely used OS on our guide.

For hosting on a Cloud platform (PaaS) like Railway, Northflank or Koyeb, refer to the "Community Guides" section as these platforms are often proprietary and closed source and may affect which may affect the viability of the guides.