v4.2.1 Release

Added

New Configuration Options:
Complete Configuration Options:

• thread_creation_send_dm_embed: True # Send embed to user when creating a thread DM
• thread_creation_menu_enabled: True # Boolean to enable or disable the thread-creation menu
• thread_creation_menu_close_on_timeout: False # Silently abort thread creation if user doesn't select an option
• thread_creation_menu_anonymous_menu: False # Anonymize the initial menu prompt relayed to staff
• thread_creation_menu_selection_log: True # Log the chosen menu option in the newly created thread channel
• thread_creation_menu_precreate_channel: False # Create thread channel immediately upon first DM even if menu is enabled
• thread_creation_menu_embed_large_image: False # Promote thumbnail to large hero image if no separate image URL is set
• thread_min_characters: 0 # Minimum characters required to create a thread
• thread_min_characters_title: "Message too short" # Title displayed when message is too short
• thread_min_characters_response: "Your message is too short to create a thread. Please provide more details." # Response text when message is too short
• thread_min_characters_footer: "Minimum {min_characters} characters required." # Footer showing required minimum characters
• snooze_default_duration: 604800 # Default snooze duration in seconds (7 days)
• snooze_title: "Thread Snoozed" # Title for the snooze notification embed
• snooze_text: "This thread has been snoozed. The channel will be restored when the user replies or a moderator unsnoozes it." # Text displayed when a thread is snoozed
• unsnooze_text: "This thread has been unsnoozed and restored." # Text displayed when a thread is unsnoozed
• unsnooze_notify_channel: "thread" # Channel to notify upon unsnooze ('thread' = same thread channel or channel ID)
• snooze_behavior: "delete" # 'delete' to delete channel, 'move' to move channel to snoozed_category_id
• snoozed_category_id: None # Category ID to move snoozed channels into when snooze_behavior == 'move'
• snooze_store_attachments: False # When True, store image attachments as base64 in snooze_data
• snooze_attachment_max_bytes: 4_194_304 # Maximum size per attachment to store as base64 (4 MiB)
• unsnooze_history_limit: None # Limit number of messages replayed when unsnoozing (None = all messages)
• thread_creation_menu_timeout: 30 # Timeout duration for user interaction with the menu (seconds)
• thread_creation_menu_embed_text: "Please select an option." # Text shown in the embed above the selection dropdown
• thread_creation_menu_dropdown_placeholder: "Select an option to contact the staff team." # Placeholder text in the dropdown before selection
• thread_creation_menu_embed_title: None # Optional title for the thread-creation menu embed
• thread_creation_menu_embed_footer: None # Optional footer text for the menu embed
• thread_creation_menu_embed_thumbnail_url: None # Optional thumbnail image URL
• thread_creation_menu_embed_image_url: None # Optional large hero image URL for the menu embed
• thread_creation_menu_embed_footer_icon_url: None # Optional URL for the footer icon
• thread_creation_menu_embed_color: str(discord.Color.green()) # Color for the menu embed's side strip

Thread-Creation Menu Feature:

• Full thread-creation menu system with interactive select menus:
  • ?threadmenu toggle: Enable/disable the menu globally.
  • ?threadmenu show: List current top-level options.
  • ?threadmenu option add: Interactive wizard to create an option.
  • ?threadmenu option edit/remove/show: Manage or inspect existing options.
  • ?threadmenu submenu create/delete/list/show: Manage submenus (nested menu levels).
  • ?threadmenu submenu option add/edit/remove: Manage options inside submenus.
  • ?threadmenu dump_config: Export current configuration to a file.
  • ?threadmenu load_config: Import configuration from a file.
  • ?threadmenu reset: Reset all thread-creation menu settings to defaults.
• Per-option category targeting: Each menu option can specify a target category where threads are created.
• Submenu support: Create up to 25 main-level options, each with up to 24 nested options.
• Optional selection logging: Log which menu option was chosen in the newly created thread channel.
• Anonymous menu support: Hide original prompt author context from staff when menu is anonymized.
• Category fallback: If an option's category is invalid/missing, creation falls back to main_category_id.

Snooze Enhancements:

• Attachment persistence for delete-behavior snoozing: Image attachments can now be stored as base64 data.
• Enhanced unsnooze functionality with configurable message replay limits.
• Auto-unsnooze task continuously monitors and automatically unsnoozes threads when duration expires.

Changed

• Renamed max_snooze_time to snooze_default_duration (accepts seconds or human-readable time like "7 days").
• When snooze_behavior is set to move, the snoozed category now has a hard limit of 49 channels. New snoozes are blocked once it’s full until space is freed.
• When switching snooze_behavior to move via ?config set, the bot reminds admins to set snoozed_category_id if it’s missing.
• Thread-creation menu options and submenu options now support per-option category targeting.
• Category selection in menu option wizards allows specifying ID, name, or mention format.
• Snoozed thread restoration now respects unsnooze_history_limit (if set) to replay only the last N messages.
• Enhanced auto-unsnooze task monitors and automatically unsnoozes threads when their snooze duration expires.
• Snoozed threads can now be moved to a dedicated category instead of being deleted (via snooze_behavior: move).

Fixed

• Corrected behavior when snooze channel count reaches the 49-channel limit in move-based snoozing.
• Improved category resolution in threadmenu wizards (handles ID, name, and mention formats reliably).
• Enhanced thread state restoration after unsnoozing to properly re-add all recipients.

Version 4.2.0 Release

Upgraded discord.py to version 2.6.3, added support for CV2.
Forwarded messages now properly show in threads, rather than showing as an empty embed.

Fixed

• Make Modmail keep working when typing is disabled due to an outage caused by Discord.
• Resolved an issue where forwarded messages appeared as empty embeds.
• Fixed internal message handling and restoration processes.
• Eliminated duplicate logs and notes.
• Addressed inconsistent use of logkey after ticket restoration.
• Fixed issues with identifying the user who sent internal messages.
• Solved an ancient bug where closing with words like evening wouldn't work.
• Fixed the command from being included in the reply in rare conditions.

Added

Commands:

• snooze: Initiates a snooze action.
• snoozed: Displays snoozed items.
• unsnooze: Reverses the snooze action.
• clearsnoozed: Clears all snoozed items.

Configuration Options:

• max_snooze_time: Sets the maximum duration for snooze.
• snooze_title: Customizes the title for snooze notifications.
• snooze_text: Customizes the text for snooze notifications.
• unsnooze_text: Customizes the text for unsnooze notifications.
• unsnooze_notify_channel: Specifies the channel for unsnooze notifications.
• thread_min_characters: Minimum number of characters required.
• thread_min_characters_title: Title shown when the message is too short.
• thread_min_characters_response: Response shown to the user if their message is too short.
• thread_min_characters_footer: Footer displaying the minimum required characters.

v4.1.2 Release (Minor Bug Patch)

Fixed

• Members not caching correctly for large servers. (PR #3365)

v4.1.1

Minor updates.

Fixed

• ?msglink now supports threads with multiple recipients. (PR #3341)
• Fixed persistent notes not working due to discord.py internal change. (PR #3324)

Added

• Support for custom activities with ?activity custom <text> (PR #3352)

v4.1.0 Release

Drops support for Python 3.9. Python 3.10 and Python 3.11 are now the only supported versions.

Fixed

• GIF stickers no longer cause the bot to crash.
• ?alias make/create as aliases to ?alias add. This improves continuity between the bot and its command structure. (PR #3195)
• Loading the blocked list with the ?blocked command takes a long time when the list is large. (PR #3242)
• Reply not being forwarded from DM. (PR #3239)
• Cleanup imports after removing/unloading a plugin. (PR #3226)
• Fixed a syntactic error in the close message when a thread is closed after a certain duration. (PR #3233)
• Removed an extra space in the help command title when the command has no parameters. (PR #3271)
• Corrected some incorrect config help descriptions. (PR #3277)
• Rate limit issue when fetch the messages due to reaction linking. (PR #3306)
• Update command fails when the plugin is invalid. (PR #3295)

Added

• ?log key <key> to retrieve the log link and view a preview using a log key. (PR #3196)
• REGISTRY_PLUGINS_ONLY, environment variable, when set, restricts to only allow adding registry plugins. (PR #3247)
• DISCORD_LOG_LEVEL environment variable to set the log level of discord.py. (PR #3216)
• STREAM_LOG_FORMAT and FILE_LOG_FORMAT environment variable to set the log format of the stream and file handlers respectively. Possible options are json and plain (default). (PR #3305)
• LOG_EXPIRATION environment variable to set the expiration time of logs. (PR #3257)
• New registry plugins: autoreact and rename.
• Improved join/leave message for multiple servers.

Changed

• Repo moved to https://github.com/modmail-dev/modmail.
• Channel name no longer shows -0 if the user has migrated to the new username system.
• ?note and ?reply now allows you to send a sticker without any message.
• Guild icons in embed footers and author urls now have a fixed size of 128. (PR #3261)
• Discord.py internal logging is now enabled by default. (PR #3216)
• The confirm-thread-creation dialog now uses buttons instead of reactions. (PR #3273)
• ?disable all no longer overrides ?disable new. (PR #3278)
• Dropped root privileges for Modmail running under Docker. (PR #3284)

Internal

• Renamed Bot.log_file_name to Bot.log_file_path. Log files are now created at temp/logs/modmail.log. (PR #3216)
• ConfigManager.get no longer accepts two positional arguments: the convert argument is now keyword-only.
• Various dependencies have been updated to their latest versions.

discord.py v2!

Modmail v4 is out with support for discord.py v2 and a variety of miscellaneous changes.

Breaking

• Modmail now requires Message Content privileged intent.
• Upgraded to discord.py v2.0 (internal changes, GH #2990).
• Python 3.8 or higher is required.
• Asyncio changes (gist)
• Plugin registry is purged and all developers have to re-apply due to breaking changes.

Added

• use_hoisted_top_role config to use change how default mod tags work, see v3.10.0#Added for details. (PR #3093)
• require_close_reason config to require a reason to close a thread. (GH #3107)
• plain_snippets config to force all snippets to be plain. (GH #3083)
• ?fpareply and ?fpreply to reply to messages with variables plainly.
• use_nickname_channel_name config to use nicknames instead of usernames for channel names. (GH #3112)
• use_random_channel_name config to use random nicknames vaguely tied to user ID. It is unable to be computed in reverse. (GH #3143)
• show_log_url_button config to show Log URL button. (GH #3122)
• Select menus for certain paginators.
• Title field in ?logs. (GH #3142)
• Snippets can be used in aliases. (GH #3108, PR #3124)
• ?snippet make/create as aliases to ?snippet add. (GH #3172, PR #3174)

Improved

• Modmail now uses per-server avatars if applicable. (GH #3048)
• Use discord relative timedeltas. (GH #3046)
• Use discord native buttons for all paginator sessions.
• ?help and ?blocked paginator sessions now have better multi-page UI.
• Autoupdate now automatically updates pipenv dependencies if possible.

Fixed

• Several minor typos. (PR #3095, PR #3116)
• Certain cases where fallback categories were not working as intended. (PR #3109)
• ?contact would create in a random category in silent mode. (GH #3091, PR #3092)
• Certain cases where ?close would fail if closer isn't in cache. (GH #3104, PR #3105)
• Stickers now work in Modmail.
• Large server sizes results in Guild.name == None. (GH #3088)
• Attachments now work on plain replies. (GH #3102)
• Support LOTTIE stickers. (GH #3119)
• Editing notes now work. (GH #3094)
• Commands now work in threads.
• Audit log searching now properly works.
• Old data causing ?blocked to fail. (GH #3131)
• Delete channel auto close functionality now works.
• Improved error handling for autoupdate. (PR #3161)
• Skip loading of already-loaded cog. (PR #3172)
• Respect plugin's cog_command_error. (GH #3170, PR #3178)
• Use silent as a typing literal for contacting. (GH #3179)

Internal

• Improve regex parsing of channel topics. (GH #3114, PR #3111)
• Add warning if deploying on a developmental version.
• Extensions are now loaded on_connect.
• MongoDB v5.0 clients are now supported. (GH #3126)
• Bump python-dotenv to v0.20.0, support for python 3.10
• Bump emoji to v1.7.0
• Bump aiohttp to v3.8.1
• Bump lottie to v0.6.11
• Remove deprecated core/decorators.py from v3.3.0

Full Changelog: v3.10.2...v4.0.0

Group Conversations!

v3.10 adds group conversations while resolving other bugs and QOL changes. It is potentially breaking to some plugins that adds functionality to threads.

Breaking

• Thread.recipient (str) is now Thread.recipients (List[str]).
• Thread.reply now returns mod_message, user_message1, user_message2... It is no longer limited at a size 2 tuple.

Added

• Ability to have group conversations with up to 5 users. (GH #143)
• Snippets are invoked case insensitively. (GH #3077, PR #3080)
• Default tags now use top hoisted role. (GH #3014)
• New thread-related config - thread_show_roles, thread_show_account_age, thread_show_join_age, thread_cancelled, thread_creation_contact_title, thread_creation_self_contact_response, thread_creation_contact_response. (GH #3072)
• use_timestamp_channel_name config to create thread channels by timestamp.

Improved

• ?contact now accepts a role or multiple users (creates a group conversation). (GH #3082)
• Aliases are now supported in autotrigger. (GH #3081)

Fixed

• Certain situations where the internal thread cache breaks and spams new channels. (GH #3022, PR #3028)
• Blocked users are now no longer allowed to use ?contact and react to contact. (COMMENT #819004157, PR #3027)
• UnicodeEncodeError will no longer be raised on Windows. (PR #3043)
• Notifications are no longer duplicated when using both ?notify and subscribe. (PR #3015)
• ?contact now works properly with both category and silent. (GH #3076)
• close_on_leave_reason now works properly when close_on_leave is enabled. (GH #3075)
• Invalid arguments are now properly catched and a proper error message is sent.
• Update database after resetting/purging all plugins. (GH #3011)
• thread_auto_close timer now only resets on non-note and replies from mods. (GH #3030)
• Deleted messages are now deleted on both ends. (GH #3041, @JerrieAries)
• Persistent notes are now properly deleted from the database. (GH #3013)
• Modmail Bot is now recognized to have OWNER permission level. This affects what can be run in autotriggers.

Internal

• Fix return types, type hints and unresolved references (PR #3009)
• Reload thread cache only when it's the first on_ready trigger. (GH #3037)
• format_channel_name is now extendable to plugins. Modify Bot.format_channel_name(bot, author, exclude_channel=None, force_null=False):. (GH #2982)

Internal Bumps

Internal

• Bumped discord.py to v1.7.3, updated all other packages to latest.
• More debug log files are now kept.
• Resolve SSL errors by retrying without SSL

Improvements to fallback channels and other QoLs

Fixed

• Certain cases where fallback categories were not working as intended. (GH #3002, PR #3003)
• There is now a proper message when trying to contact a bot.

Improved

• ?mention can now be disabled with ?mention disable. (PR #2993)
• ?mention now allows vague entries such as everyone or all. (PR #2993)

Internal

• Change heroku python version to 3.9.4 (PR #3001)

Improving react to contact and potentially breaking plugin changes

Breaking

• on_thread_initiate and on_thread_ready events now have thread, creator, category, initial_message as additional arguments.

Fixed

• confirm_thread_creation now properly works when a user opens a thread using react to contact. (GH #2930, PR #2971)
• ?disable all/new now disables react to contact threads. (GH #2969, PR #2971)
• Ghost errors are no longer raised when threads are created using non-organic methods.

Internal

• thread.reply now returns (msg_to_user, msg_to_thread). Can be useful in plugins.