Mastodon instance administrators often need to control who can join their server. One effective method is restricting new user registrations to specific email domains. This prevents spam accounts and ensures users belong to a trusted organization or community. This article explains how to configure email domain whitelisting or blacklisting in Mastodon’s settings.
Key Takeaways: Restrict Mastodon Registrations by Email Domain
- Administration > Server Settings > Registrations: Enables whitelist or blacklist mode for email domains.
- Whitelist mode: Only users with email addresses from approved domains can register.
- Blacklist mode: Blocks registration from specific domains while allowing all others.
Understanding Email Domain Restrictions in Mastodon
Mastodon allows instance administrators to control registrations based on the domain part of a user’s email address. This feature is built into the Mastodon admin panel and does not require editing configuration files or restarting the server. You can choose between two modes: whitelist (allow only specified domains) or blacklist (block specified domains). The whitelist mode is ideal for closed communities like a company or school. The blacklist mode is useful for blocking known spam domains while keeping registrations open to other domains. Changes take effect immediately after saving.
Steps to Restrict Registrations by Email Domain
Follow these steps to configure email domain restrictions in your Mastodon instance. You must have administrator access to the Mastodon web interface.
- Open the Server Settings page
Sign in to your Mastodon account with admin privileges. Click the Preferences icon in the top-right navigation bar. From the menu, select Administration and then Server Settings. - Navigate to the Registrations section
In the left sidebar, click Registrations. This page contains all options related to new user sign-ups. - Choose the restriction mode
Under the Email domain whitelist or Email domain blacklist section, select the appropriate mode. For whitelist, check the box that says Enable email domain whitelist. For blacklist, check Enable email domain blacklist. You cannot enable both at the same time. - Add allowed or blocked domains
In the text field below the checkbox, enter one domain per line. For example, to allow only company.com, typecompany.comon its own line. To block spam.com, enterspam.com. Do not include the @ symbol or any wildcards. Mastodon matches the exact domain part of the email address. - Save the changes
Click the Save changes button at the bottom of the page. The new restrictions apply immediately. New users attempting to register with an unapproved or blocked domain will see an error message.
Common Mistakes and Limitations
Domain format errors
Entering domains with the @ symbol or with subdomains like mail.company.com can cause the restriction to fail. Use only the root domain, such as company.com. Mastodon checks the domain after the @ symbol in the email address. For example, an email user@sub.company.com has the domain sub.company.com, not company.com. If you want to allow all subdomains of company.com, you must add company.com and all subdomains explicitly.
Whitelist and blacklist cannot be used together
Mastodon does not support using both a whitelist and a blacklist simultaneously. If you need to allow only a few domains while also blocking specific subdomains, use the whitelist mode and list only the allowed domains. There is no way to create exceptions within a whitelist.
Changes do not affect existing users
Restricting registrations by email domain only applies to new sign-ups. Existing users with email addresses from blocked domains are not removed or affected. To manage existing accounts, you must manually disable or delete them from the admin panel under Administration > Accounts.
Open registration must be enabled
If you set registrations to Closed or Approval required in the same Registrations page, the domain restrictions have no effect. The domain whitelist or blacklist only works when registrations are set to Open. Ensure that the registration mode is set to Open for the domain restrictions to apply.
Whitelist vs Blacklist: Which Mode to Choose
The following table summarizes the key differences between whitelist and blacklist modes.
| Item | Whitelist Mode | Blacklist Mode |
|---|---|---|
| Default behavior | Blocks all domains except those listed | Allows all domains except those listed |
| Best use case | Private communities, company or school instances | Public instances wanting to block known spam domains |
| Maintenance | Requires adding each allowed domain manually | Requires adding each blocked domain as needed |
| Risk | Legitimate users from unlisted domains cannot register | Spam domains not yet listed can still register |
Choosing between whitelist and blacklist depends on your instance’s goals. For a private server, use whitelist mode. For a public server with spam issues, start with blacklist mode and update the list as new spam domains appear.
You can now control who joins your Mastodon instance by restricting registrations to specific email domains. Start by deciding whether whitelist or blacklist mode suits your community. Then add the relevant domains in the Server Settings page. For advanced control, consider combining domain restrictions with registration approval to manually verify each new user.