Welcome to ModMail! This guide will walk you through the typical workflow of handling user threads, from when a thread first appears to closing threads.
- Quick Start
- When a New Thread Appears
- Replying to Users
- Editing and Deleting Messages
- Using Snippets for Common Responses
- Organizing Your Conversation
- Interactive Notifications
- Wrapping Up Threads
- Tips
- Troubleshooting
Note
This guide uses commands like -command. You can change the prefix with the
-settings command. If you have a different prefix, replace - with your
chosen prefix in the examples below.
New to ModMail? Here's what you need to know to get started:
- New threads appear automatically when users DM the bot
- Reply with
-reply(or-r) to respond with your username visible - Reply with
-areply(or-ar) to respond anonymously - Close threads with
-closewhen the conversation is done - Type
-helpto see all available commands
More details on each step are below!
When a user sends a DM to the bot, you'll see a new thread pop up in the forum channel. Each thread comes loaded with helpful context about the user - their account creation date, when they joined the server, their current roles, and which mutual servers they share with the bot.
You can also manually create a thread for a user by using the -contact
command. Use -contact @user or -contact [user_id] to start a new
conversation with someone. This is useful for reaching out proactively or
following up on issues without needing the user to DM the bot first.
-contact @username
-contact 123456789012345678
Tip
Want to make sure all staff members are automatically added to new threads?
Add a notification role in the -settings command, with the notifications set
to silent if desired.
You have several ways to reply to a recipient:
When you want to stay anonymous, use -areply (or -ar). This hides your
username from the user and only shows the server name.
-ar Hello! Who am I? I don't know either!
What the user sees: A message from your server name (not your username)
When you want to show who's helping, use -reply (or -r for short). This
shows your username to the user, so they know who they're talking to.
-r Hi it's me!
What the user sees: A message from your server name AND your username
For special cases like Discord invites that need to work properly, use
-preply (or -pr) for plain text replies. This removes embed formatting so
things like invite links actually function.
-preply Here's an invite! discord.gg/example
There's also -apreply (or -apr) if you want anonymous plain text replies.
Made a typo or need to clarify something? No problem! Reply to the message
you want to edit with -edit [new content] (or just e).
If you need to delete a message entirely, reply to the message you want to
delete with delete (or d).
Tip
Any staff member can edit or delete messages in the thread.
Tired of typing the same responses over and over? Snippets are your friend!
Create commonly used responses with -snippet add [name] [content].
Examples:
-snippet add server-rules Please review our server rules in #rules
-snippet add ban-appeal To appeal a ban, join the appeal server: [link]
-snippet add welcome Welcome to our server! Feel free to ask any questions.
When you need to use a snippet, just type -[snippetname] and the bot will send
that content.
Examples:
-server-rulessends the "server-rules" snippet content-ban-appealsends the ban appeal information-welcomesends the welcome message
- View all snippets:
-snippet list - Edit a snippet:
-snippet edit [name] [new content] - Delete a snippet:
-snippet delete [name]
You can optionally rename threads to reflect what the issue is actually about. Instead of just threads with the default username and ID, you could rename it to something like "Ban Appeal - User#1234" or "Question about xyz - User#1234".
Feel free to add forum tags to categorize the conversation - maybe "Appeal", "Question", "Bug Report", etc.
Important
If you want to change forum tags, make sure you don't remove the Open and Closed tags that the bot manages automatically.
The bot relays reactions between you and the user. React to messages in the staff thread and those reactions will appear in the user's DM (as long as the bot has access to those emojis). The user's reactions to their own messages will also show up in your thread.
If users join or leave servers while you're talking, you'll see notifications pop up in the thread.
When you've resolved the user's issue or the conversation has naturally
concluded, use the -close command to close and archive it.
Note
The bot won't send a DM to the user when you close since closing a thread is only for staff reference.
Closed threads will always stay in Discord as closed threads, so you can always refer back to them without any risk of losing information due to bot downtime or if you decide to use a different bot in the future.
- The bot will re-upload images and files sent by users, so you can always access them later in the thread without risk of losing them if the user decides to delete their original message.
- You can discuss internally in threads before replying to users - anything without a command prefix stays between staff.
- Use the
-helpcommand anytime to see all available commands
Commands not working?
- Check that the bot has the right permissions in the forum channel
- Verify you're using the correct command prefix (check with
-settings) - Make sure you're in the correct thread/channel
Messages not being delivered?
- Ensure the bot can DM the user (they haven't blocked the bot)
- Check if the user has DMs disabled for server members
Thread not appearing?
- Confirm the bot has "Create Public Threads" permission in the forum channel
Images/files not uploading?
- Verify the bot has "Attach Files" permission
- Ensure the bot has permissions in the forum channel to send message and attach files
If there are any failures with relaying messages, an error log thread will be created in the forum channel with details about what went wrong. If they're difficult to understand, you can share them in the support server for help.
If issues persist or error messages are unclear, feel free to ask for help in the support server.