Kyber edited this page Jan 8, 2019 · 26 revisions

Heroku Installation

Heroku Account

You need to make a Heroku account. Make one at Heroku's Website and then follow the steps below or watch the video tutorial:

Creating a bot account

  1. Create a Bot Application for Discord
  2. Head over to the applicatons page.
  3. Click “new application”. Give it a name, picture and description.
  4. Click “Create Bot User” and click “Yes, Do It!” when the dialog pops up.
  5. Copy down the bot token. This is what is used to login to your bot and will be used at Step 3, or 11 if you are setting up on your PC.

Here's a GIF to explain the first 5 steps

Getting the Mod Mail API Token

This been made mandatory since v2.0.0 and is required if you wish to update from v1.x to v2.0

  1. Go to our website and login via Github, click here. If you are worried about security and what we will do with your token, you may read the bottom of this page.
  2. Copy down the API token. This is what is used to interact with our server-side API for features such as logs and auto-updating. This is what is used at Step 4.

Deploying the bot


  1. Input a name of your choosing for your app, the heroku app name is not important.
  2. Input your bot token into the TOKEN field.
  3. Input your API token into the MODMAIL_API_TOKEN field.
  4. Put the ID of your Server into the GUILD_ID field.
  5. Put your own ID in the OWNERS field.
  6. Click the deploy app button and wait for it to finish.
  7. Go into your Heroku app dashboard > deploy > and click connect to GitHub.
  8. Search for modmail and click connect. Note: it should say your GitHub name instead of kyb3r.
  9. Click enable automatic deploys
  10. Click manage app and go into the resources tab.
  11. Now turn on the worker by clicking the pencil icon.
  12. If you want, you can go over and check the application logs to see if everything is running smoothly.
  13. Once the bot is online in your server, do [your prefix]setup and you are good to go!

You can add the bot to your server with this tool. Your Client ID is retrived from the applicatons page

Now you should be done. Go over to discord and try it out! If you have any issues, join the discord server. If you use the bot a star on this repository is appreciated!

Make sure to give the bot Manage Channels and Manage Messages permissions!

Self-Hosting on your own PC or VPS

This is discouraged if you don't know what you are doing and we will not help you along the way. Use the Heroku method instead, as commands such as update and auto-update functionality will only work with it.


Your Modmail API Token provides us with the following information:

Grants read/write access to code, commit statuses, collaborators, and deployment statuses for public repositories and organizations. Also required for starring public repositories.
  • We use this token to allow you to automatically update the repository.
  • The Client side code to interact with the API is opensource, take a look.
  • Our API Server code is opensource, take a look.
  • We store your token and other associated data in a MongoDB database.
  • We do not use your API Token anywhere else that is not opensource.
  • All Github API requests are stemmed from user commands except the following scenarios:
    • Auto-updating would modify your current fork to host the latest version.
  • The MongoDB URI is not public.
  • You can regenerate your API Token at any time by visiting the dashboard.
  • The following data is associated with your API Token:
    • Modmail thread logs
    • Github token
    • Github username
    • Config Data (Snippets, prefix, playing status, etc.)
    • Metadata (ping, member count, etc)

Security Issues

We take security very seriously. Please use the right avenues as stated below to report any security issues. For important updates, remember to join our discord server

  • If you have found a security issue, you can create a Github issue and we will take a look at it.
  • If the issue is too dangerous and you are afraid that other people might abuse the bug, DM Mod Mail on the Code Grok discord server.
  • If you wish for us to delete all data associated with your API token and Github token, DM Mod Mail on the Code Grok discord server.
  • If you wish to view all data associated with your API token and Github token, DM Mod Mail on the Code Grok discord server.
  • If Mod Mail is down, you can DM Kyber#6969 or 4JR#4895.

Other than that, enjoy the bot!

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.