How to Add a Custom Welcome Email on a Mastodon Instance

When users join your Mastodon instance, they receive a default welcome email generated by the server. This generic message does not reflect your community’s identity or provide specific guidance for new members. Customizing the welcome email lets you introduce your instance’s rules, recommended hashtags, and local culture. This article explains how an instance administrator can create and deploy a custom welcome email template using the Mastodon administrative interface.

Understanding the Mastodon Welcome Email System

Mastodon sends a welcome email to every newly registered user immediately after account confirmation. The default email is a plain text message that says “Welcome to Mastodon” and includes basic login instructions. This message is generated by the UserMailer module in the Mastodon application code. You cannot edit the default email through the web interface without customizing the template.

The Mastodon administrative interface includes a feature called Site Settings where you can configure many instance-wide options. One of these settings is the User Mailer section, which provides a text area for a custom welcome email body. This template supports a small set of variables that are replaced with user-specific values when the email is sent.

To customize the welcome email, you must be an instance administrator with access to the Administration dashboard. The change applies to all new users who register after the template is saved. Existing users do not receive the updated email retroactively.

Steps to Add a Custom Welcome Email on Your Mastodon Instance

1. Log in as an administrator
   Use an account that has the Administrator role on your Mastodon instance. Only administrators can access the Site Settings panel.
2. Open the Administration menu
   Click the hamburger menu icon in the top-left corner of the Mastodon interface. Select Preferences from the dropdown menu. On the Preferences page, click Administration in the left sidebar.
3. Navigate to Site Settings
   Under the Administration section, click Site Settings. This page contains all configurable instance-level options.
4. Locate the User Mailer section
   Scroll down the Site Settings page until you see the heading User Mailer. This section contains a single text area labeled Welcome email body.
5. Write your custom email template
   In the text area, type the email body you want new users to receive. You can use the following variables that Mastodon will replace with actual values:
   • {{username}} — The user’s display name as set in their profile.
   • {{instance_name}} — The instance name defined in Site Settings under Site Title.
   • {{email}} — The user’s email address.
   • {{account_url}} — The URL to the user’s profile page.

   Example template:

   Welcome to {{instance_name}}, {{username}}!

   We are glad you joined. Here are a few tips to get started:
   - Introduce yourself using the hashtag #introductions
   - Read the instance rules at /about/more
   - Follow the admin account at @admin

   Your profile is at {{account_url}}.

   Happy tooting!

6. Save the settings
   Click the Save changes button at the bottom of the Site Settings page. Mastodon will apply the new welcome email template immediately.
7. Test the custom email
   Create a new test account on your instance using a separate email address. Verify that the welcome email contains your custom message and that all variables are replaced correctly.

Common Mistakes and Limitations to Avoid

Custom Email Does Not Include Instance Rules or Links

The default welcome email does not include instance rules or links to important pages. Your custom template should explicitly mention the instance rules page URL or any other resources new users need. Mastodon does not inject these automatically. You must type the full URL, for example https://yourinstance.social/about/more.

Variables Appear as Plain Text Instead of Being Replaced

If you see {{username}} displayed literally in the email, the variable name is misspelled or uses incorrect brackets. Use exactly two curly braces on each side with no spaces. Also ensure you are using the variable names listed above. Mastodon ignores any unrecognized variables and leaves them as plain text.

Email Does Not Send After Changing the Template

The custom welcome email only applies to new registrations that occur after you save the settings. Existing users will not receive the updated email. If you want to resend a welcome email to existing users, you must use a third-party tool or write a custom script using the Mastodon API. The administrative interface does not offer a resend option.

HTML Formatting Does Not Render Correctly

The welcome email is sent as plain text, not HTML. Do not use HTML tags like <b> or <a>. Mastodon will display them as plain text in the email body. Use plain text formatting with line breaks to structure your message.

Item	Default Welcome Email	Custom Welcome Email
Content	Generic Mastodon template	Administrator-written text
Variables supported	None	{{username}}, {{instance_name}}, {{email}}, {{account_url}}
Format	Plain text	Plain text
Update scope	All new users	New users after template save
Editing location	Not editable	Administration > Site Settings > User Mailer

With a custom welcome email, you can provide new users with immediate guidance and a sense of community. Start by drafting a short message that includes your instance rules and a recommended first hashtag. After saving the template, test with a fresh account to confirm the variables work. For advanced customization, consider editing the Mastodon source code directly or using the API to trigger custom notification emails.