Mastodon Migration Notification Email Not Sent: Causes

When you move your Mastodon account from one instance to another, the platform is supposed to send notification emails to your followers on your old instance. Many users report that these migration notification emails never arrive. The root cause is often a misconfiguration in the old instance’s email delivery system or a missing verification step during the migration process. This article explains why Mastodon fails to send migration notification emails and how to identify and resolve the underlying issues.

Why Mastodon Fails to Send Migration Notification Emails

Mastodon uses a background job system to send emails when a user initiates an account migration. When you start the migration from your old account, Mastodon queues a job that sends notification emails to your followers. If the email delivery fails, the job retries several times before giving up. The most common reasons for failure are related to email server configuration, missing verification, or database lock issues.

Email Server Configuration Problems

Mastodon relies on an SMTP server to send emails. The SMTP settings are stored in the .env.production file on the server. Common misconfigurations include incorrect SMTP hostname, wrong port number, missing authentication credentials, or an unverified sender domain. If the SMTP server rejects the connection, Mastodon cannot deliver the migration notification email. Check the Mastodon server logs for entries like Net::SMTPAuthenticationError or Net::SMTPFatalError to identify SMTP issues.

Missing Email Verification on the New Account

Mastodon requires that the new account has a verified email address before the migration process can proceed. If you created the new account but did not click the verification link sent to your email, Mastodon will not send migration notifications. The system treats the new account as unverified and blocks the email queue for that account. Verify your new account’s email by checking your inbox for a message from the new instance. If you do not see the verification email, request a new one from the instance settings.

Database Lock or Job Queue Backlog

Mastodon uses Sidekiq to process background jobs, including email delivery. If the Sidekiq queue is backlogged or a job fails due to a database lock, the migration notification email may never be sent. Large instances with many active users can experience Sidekiq delays. Check the Sidekiq dashboard at /sidekiq on your instance to see if the email job is stuck or has failed. Restarting Sidekiq or clearing the queue can resolve this issue.

Steps to Diagnose and Fix Migration Email Delivery

Follow these steps to identify the cause of missing notification emails and resolve the problem.

1. Check the new account’s email verification status
   Log in to your new Mastodon account. Go to Preferences > Account. Look for a banner that says your email is unverified. If present, click the link to resend the verification email. Open the email and click the confirmation link. Wait 5 minutes, then check your old account to see if the migration email was sent.
2. Review the SMTP configuration on the old instance
   If you are an instance admin, open the .env.production file located in the Mastodon directory. Verify the SMTP settings: SMTP_SERVER, SMTP_PORT, SMTP_LOGIN, SMTP_PASSWORD, and SMTP_FROM_ADDRESS. Ensure the port matches your SMTP provider (587 for STARTTLS, 465 for SSL/TLS). Test the SMTP connection by running rails runner 'UserMailer.test_email("you@example.com").deliver_now' from the Mastodon Rails console.
3. Check the Sidekiq job status
   Access the Sidekiq web interface at https://your-instance.example/sidekiq. Look for failed jobs in the Retries or Dead tabs. Search for jobs with the class NotificationMailer or AccountMigrationMailer. If you see failed jobs, click the job to view the error message. Common errors include Net::OpenTimeout (SMTP server unreachable) or ActiveRecord::RecordNotFound (account deleted).
4. Restart Sidekiq and clear the queue
   SSH into your Mastodon server. Run sudo systemctl restart mastodon-sidekiq to restart the Sidekiq service. If the queue is stuck, clear it by running sudo -u mastodon bash -c 'cd /home/mastodon/live && RAILS_ENV=production bundle exec sidekiqctl stop' followed by a restart. This forces Mastodon to reprocess pending email jobs.
5. Manually trigger the migration email
   If the automatic email fails, you can send it manually from the Mastodon Rails console. Run sudo -u mastodon bash -c 'cd /home/mastodon/live && RAILS_ENV=production bundle exec rails c'. Then execute old_account = Account.find_local('old_username@old_instance.social'); new_account = Account.find_local('new_username@new_instance.social'); AccountMigration.new(old_account, new_account).perform!. This bypasses the queue and sends the notification immediately.

If Mastodon Still Has Issues After the Main Fix

Migration Email Marked as Spam by Email Providers

Some email providers like Gmail or Outlook may flag Mastodon’s migration notification as spam. This happens when the instance’s sending domain lacks proper SPF, DKIM, or DMARC records. Ask your followers to check their spam or junk folders. As an instance admin, add SPF and DKIM records to your domain’s DNS settings to improve deliverability. Use a tool like MXToolbox to verify your DNS records.

Followers on Remote Instances Do Not Receive the Email

Mastodon sends migration notification emails only to followers on the same instance as the old account. Followers on other instances receive a notification through the ActivityPub protocol instead of email. If your old instance has few local followers, the email notification will appear to be missing because it was never sent to remote users. Check the old instance’s local follower count in Preferences > Account > Followers and following.

Email Job Stuck in a Loop Without Error

In rare cases, the Sidekiq job for the migration email enters an infinite retry loop without logging an error. This occurs when the job encounters a transient network issue. Restarting Sidekiq as described in Step 4 usually breaks the loop. If the problem persists, delete the old migration job from the Sidekiq queue and initiate the migration again from the old account’s settings.

Mastodon Migration Email Delivery: Self-Hosted vs Managed Instances

Item	Self-Hosted Instance	Managed Instance
Email server control	Full control over SMTP settings in .env.production	Relies on instance admin’s email configuration
Common failure point	Misconfigured SMTP host, port, or credentials	Instance admin has disabled outbound email
Diagnostic access	SSH and Rails console available to admin	Limited to web interface; must contact support
Email deliverability	Admin must set up SPF, DKIM, DMARC	Managed provider handles DNS records
Recovery time	Minutes to hours depending on admin expertise	Hours to days depending on support queue

Understanding these differences helps you choose the right troubleshooting path. Self-hosted instance users can directly edit configuration files. Managed instance users must submit a support ticket to the instance admin. In both cases, verifying the new account’s email and checking Sidekiq logs are the first steps.