Migrate mail addresses

Move your domain's mailboxes to Uberspace 8 in stages: prepare the destination, copy existing messages, change DNS, and copy any messages that arrived at the old provider during the transition. Keep the old service available until you have checked the result.

Prerequisites

You need a Uberspace 8 Asteroid with SSH access, control of your domain's DNS, and IMAP access to each source mailbox. Check available storage and keep a backup of important mail. Record the old DNS settings for rollback.

The examples use isabell.example, the mailbox info@isabell.example, and the Asteroid hostname moondust.uberspace.de. Replace these with your own values. Command output is illustrative and sometimes shortened.

Moving from Uberspace 7

Uberspace 8 uses full mail addresses and separate mailboxes per domain. info@isabell.uber.space is not automatically the mailbox for info@isabell.example. Create the destination address explicitly. Mail is stored centrally; copying ~/Maildir or ~/users is not a migration method on Uberspace 8. See the migration overview.

Set up mail domain

Add your domain on the destination Asteroid before creating its mailboxes:

[isabell@moondust ~]$ uberspace mail domain add isabell.example
OK: Added maildomain 'isabell.example' to your Asteroid

Use the following values for your DNS:
...

Save the DNS records printed by the command. First publish the uberspace-mail-... verification TXT record at your DNS provider, leaving the current MX records in place. This allows ownership validation while incoming mail continues to reach the old provider. Use the token printed for your domain, not a token copied from an example.

Check after a few minutes:

[isabell@moondust ~]$ uberspace mail domain show isabell.example
Domain: isabell.example
DNS state: VALID
...

If validation has not completed, check the TXT record and try again later. The Manual's mail domain chapter explains verification and the DNS records in detail.

Set up your mailaddresses

Create each destination mailbox using its full address:

[isabell@moondust ~]$ uberspace mail address add info@isabell.example
enter password (hidden):
confirm password (hidden):
OK: Added mailaddress 'info@isabell.example' to your Asteroid

Set a strong mailbox password and keep it for the import and your mail client. It is separate from the Asteroid's SSH password. Repeat this for every mailbox you want to migrate. Recreate aliases and forwards using the Uberspace 8 mail address settings; they are not copied by IMAP.

For example, a forward without a separate archive can be configured as follows:

[isabell@moondust ~]$ uberspace mail address add forwardme@isabell.example --forward mail@otherprovider.example
OK: Added mailaddress 'forwardme@isabell.example' to your Asteroid

Import mails

Uberspace 8 provides imapsync. Run it on your destination Asteroid. Use your old provider's IMAP hostname for --host1 and your new Asteroid's hostname for --host2. These are explicit server connections, so they do not depend on where your domain's MX currently points. Do not use localhost as the destination mail server.

Start with a dry run. Paste the whole command, including the continuation lines, after replacing the hostnames and usernames:

[isabell@moondust ~]$ imapsync \
  --host1 imap.oldprovider.example --user1 info@isabell.example \
  --ssl1 --sslargs1 SSL_verify_mode=1 \
  --host2 moondust.uberspace.de --user2 info@isabell.example \
  --ssl2 --sslargs2 SSL_verify_mode=1 \
  --logdir "$HOME/logs/imapsync" \
  --dry
...
Exiting with return value 0 (EX_OK: successful termination) ...

The tool asks for the source and destination passwords interactively; enter them at the prompts. Avoid password arguments in your shell history. The --ssl options require encrypted connections, and SSL_verify_mode=1 enables certificate verification on both connections. See imapsync's security documentation.

Read the dry-run log to check both logins and folder names. It does not copy messages. Once the proposed transfer is correct, run the same command with the final --dry line removed (also remove the preceding line's trailing \). The real run reports transferred messages and a final return value. Confirm that it finishes successfully and inspect the log for errors.

The command copies messages without requesting source deletion. Keep the same folder mapping for later runs: imapsync normally skips messages already copied. For a large archive, use a persistent terminal session such as tmux so disconnecting your SSH client does not interrupt it.

Gmail and other OAuth providers

Some providers require an app password or OAuth instead of a normal account password. Follow your source provider's requirements and the imapsync OAuth instructions. The generic password example above does not configure OAuth or Gmail's label handling for you.

Switch delivery to Uberspace 8

Before switching, connect your mail client to the destination hostname on port 993 with SSL/TLS, using the full destination address and its mailbox password. Check folders, message dates, and several attachments. Repeat the import and these checks for every mailbox.

Then update DNS with the records from uberspace mail domain show:

• Point the domain's MX to in-mx.uberspace.de.; replace the old provider's MX records rather than leaving both providers active. If your DNS interface requires a priority, use 0.
• Keep the verification TXT record.
• Configure both DKIM CNAMEs printed by the command.
• Update your existing SPF TXT record to authorize Uberspace. Publish only one SPF record; keep any other senders you still use authorized during the transition. Review an existing DMARC policy when changing senders.

Do not point the MX at your individual Asteroid hostname: Uberspace 8 uses a shared incoming mail service. Changing mail records does not require changing your website's A or AAAA records.

Example DNS check after the change:

[isabell@moondust ~]$ dig isabell.example MX +short
0 in-mx.uberspace.de.

A VALID domain status confirms ownership validation, not that every DNS resolver has stopped using the old MX. Leave the old mailbox active through the DNS cache lifetime and while mail is still arriving there. Run the same imapsync command again to collect those messages, then check both mailboxes.

Update your clients' incoming and outgoing settings using the Manual's mail access table. Send a test message to and from an external account you control. Retire the old service only after the final sync and delivery checks succeed.

Troubleshooting

Accessing your new mailbox

Use the Asteroid hostname, the full primary mailbox address, and its mailbox password. An alias is not a separate mailbox. Check the mail access instructions instead of relying on the Uberspace 7 webmailer.

DNS invalid

If the domain is still unvalidated, inspect its TXT records and compare the verification token with the one printed by Uberspace:

[isabell@moondust ~]$ dig isabell.example TXT +short
"uberspace-mail-<your-domain-token>"
"v=spf1 include:spf.uberspace.de ~all"

The token shown here is a placeholder. Check the record name with your DNS provider, and allow for cached answers. Do not remove and recreate the domain to force validation: removing a mail domain also deletes its mailboxes.

Multiple spamfolders

Providers name special folders differently. Check the dry run and your client's Sent, Drafts, and Junk folder assignments. If needed, consult imapsync's folder mapping options before copying; test changed mappings with a dry run first.

Missing calendars and contacts

IMAP copies mail, not calendars, address books, filters, or forwarding rules. Export those separately and recreate the needed configuration. For hosted calendars and contacts, see the Nextcloud or Baïkal Guides.