Docs / Surfaces / Email

Email over IMAP

You back up a mailbox over IMAP with one command, and restore it as .eml files that any mail client opens.

# any IMAP server that accepts a password: Gmail, Fastmail, self-hosted
export SAFEGRD_EMAIL_PASSWORD='your-app-password'
safegrd backup --email --email-host imap.example.com --email-user ops@example.com

SafeGrd fetches each message as RFC 5322 and streams it into the sealed archive, keeping the folder structure. It backs up every folder except spam and trash. To back up fewer, name them with --email-folders.

Put the password in SAFEGRD_EMAIL_PASSWORD instead of passing --email-password. A password given as a flag shows up in shell history and in the process list.

Providers

ProviderIMAP serverPassword
Gmail and Google Workspaceimap.gmail.com:993An app password, which you create at myaccount.google.com/apppasswords. The account needs 2-Step Verification. A Workspace administrator can turn app passwords off.
Fastmailimap.fastmail.com:993An app password with IMAP access: Settings, Privacy & Security, Manage app passwords and access.
Microsoft 365 and Outlook.comNot supported yetMicrosoft turned off password sign-in for IMAP, app passwords included, and requires OAuth. SafeGrd signs in with a password, so it cannot back up these mailboxes until it supports OAuth.
Self-hosted (Dovecot, Cyrus and others)Your server, port 993The mailbox's password. For a certificate from an internal CA, see below.

Gmail labels

Gmail shows each label as a folder, so one message can appear in several folders. SafeGrd backs up only Gmail's All Mail folder and records each message's labels beside it. Each message is downloaded and stored once. Spam and Trash are left out.

For this to work, All Mail has to be visible over IMAP. It is by default. To check, open the Labels tab in Gmail's settings and make sure Show in IMAP is ticked for All Mail. If it is off, the backup reads one folder per label instead. It stores a message once for each label it has, and prints a warning. If you list folders on the surface, SafeGrd backs up exactly the folders you named.

One Gmail message with the labels Inbox and Work. With All Mail shown in IMAP, SafeGrd reads All Mail only: the message is stored once and its labels go in the manifest. With All Mail hidden, it reads one folder per label, Inbox and Work: the message is stored twice and the backup prints a warning. One message labels: Inbox, Work All Mail shown in IMAP All Mail hidden All Mail Inbox Work Stored once labels in the manifest Stored twice and a warning
Why Show in IMAP on All Mail matters: without it, a message with five labels is stored five times.

Where the password comes from

By default the password stays on the host. The surface's credential block says from: env with the variable's name, from: command with a command that prints the password, or from: file. SafeGrd learns the variable's name and never sees the password.

To have SafeGrd hold the password instead, set credential: {from: safegrd} on the surface and name nothing on the host. SafeGrd keeps the password encrypted and gives it only to this surface's host when the mailbox is due. The daemon keeps it in memory for that run. Add it in the setup wizard, or open the surface under Surfaces, click Edit, then Add credential.

SafeGrd refuses an incomplete block, such as from: env with no name, instead of guessing.

A mailbox behind a private CA

If your mail server's certificate chains to an internal CA, point the surface at a PEM bundle on the host with ca_file: /etc/ssl/mail-ca.pem. For a one-off backup, pass --email-ca-file. SAFEGRD_EMAIL_CA_FILE sets the bundle for every email surface on the host that does not name its own. SafeGrd adds the bundle to the system roots and still trusts them. You cannot turn certificate checks off, because the mailbox password travels over this connection.

Restoring a mailbox

safegrd restore --snapshot <id> --target-dir /restored/mailbox

You get one directory per folder, with each message as a standard RFC 5322 .eml file. Any mail client or forensic tool can open or import them.

A Gmail mailbox comes back as one All Mail directory. Its labels are in .safegrd-email-manifest.json at the top of the target directory, which lists each message's path with its labels, such as \Inbox or Work.

What a Fire Drill checks

The drill checks that the message count matches the manifest and that every message's SHA-256 matches. It fails if the archive holds a message the manifest does not list, or if a message the manifest lists is missing. It also reads each message's headers as RFC 5322 mail and reports how many do not parse. Those messages were stored that way on the mail server, often old spam. They are restored byte for byte and do not fail the drill. The drill writes nothing to disk.