Email over IMAP
You back up a mailbox over IMAP with one command, and restore it as .eml files
that any mail client opens.
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
| Provider | IMAP server | Password |
|---|---|---|
| Gmail and Google Workspace | imap.gmail.com:993 | An app password, which you create at myaccount.google.com/apppasswords. The account needs 2-Step Verification. A Workspace administrator can turn app passwords off. |
| Fastmail | imap.fastmail.com:993 | An app password with IMAP access: Settings, Privacy & Security, Manage app passwords and access. |
| Microsoft 365 and Outlook.com | Not supported yet | Microsoft 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 993 | The 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.
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
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.