Scan Email Over IMAP

PII Crawler can scan an email account directly over IMAP. It connects to the mail server, lists your folders, and scans every message where it lives: each message is fetched into memory, its body and attachments are scanned, and the bytes are discarded. Nothing is downloaded to disk, so scanning your mailbox never creates a second copy of your PII.

The mailbox is opened read-only. PII Crawler uses the IMAP EXAMINE command and BODY.PEEK fetches, which means your messages are never marked as read, no flags change, and nothing is moved or deleted. Your mail client will not notice anything happened.

This works with any standard IMAP server: Fastmail, Gmail (with an app password), iCloud, Zoho, Dovecot, Courier, a NAS mail server, and most corporate mail systems that still expose IMAP.

What you'll need

• The IMAP server hostname (for example imap.fastmail.com or imap.gmail.com). Your provider's help pages list it, usually under "IMAP settings".
• The port: 993 for regular IMAP over TLS (the default), or 143 with STARTTLS.
• Your username, usually your full email address.
• An app password in most cases. Providers with two-factor authentication (Gmail, Fastmail, iCloud, Zoho) do not accept your normal account password over IMAP; they let you generate a per-app password instead:
  • Gmail: myaccount.google.com, Security, 2-Step Verification, App passwords. If your organization has disabled app passwords, use the Google Takeout export path instead.
  • Fastmail: Settings, Privacy & Security, Integrations, New app password.
  • iCloud: appleid.apple.com, Sign-In and Security, App-Specific Passwords.
• Microsoft 365 / Outlook.com: Microsoft has retired basic authentication for IMAP, so most Microsoft accounts cannot connect this way. Exchange Online support is on the roadmap.

How your password is protected

Scans started from the TUI or web UI store the account password in the same encrypted credential store used for network shares: AES-256-GCM under a data-encryption key that is itself wrapped with a key derived (via Argon2id) from a credential password you choose. Someone who steals the database file cannot read the password without that credential password. See How credentials are protected for the full details, including the no-recovery warning.

CLI scans never persist the password at all: it is read from an environment variable, handed to the scan engine in memory, and forgotten when the process exits.

The connection always uses TLS with certificate validation. There is no insecure mode. On Linux and Windows, if your mail server uses a self-signed certificate, install that certificate into the operating system trust store and PII Crawler will accept it. On macOS, PII Crawler validates against its own bundled set of publicly trusted certificate authorities and does not read the system Keychain, so servers with self-signed or private-CA certificates are not supported there.

Which folders are scanned

By default, every selectable folder is scanned, including Junk and Trash. That is deliberate: leaked PII loves to hide in spam replies and deleted mail.

Virtual duplicate views are skipped automatically so messages are not scanned twice. On Gmail that means All Mail, Important, and Starred are excluded; the real folders (Inbox, Sent Mail, labels) cover everything they contain.

You can narrow the scan to specific folders in every interface. Selecting a folder also includes everything nested under it, so choosing Work covers Work/Clients too.

Scanning from the web UI

1. Open Create Scan and choose the Email (IMAP) scan type.
2. Enter the server, username, and app password. Check Use STARTTLS only if your server uses port 143.
3. Click Test & List Folders. On success you get a checkbox list of your folders, with duplicate views unchecked. Adjust the selection if you want a narrower scan.
4. Start the scan. Progress, findings, and the files view work exactly like any other scan; each message appears as its own entry named after its folder, message number, and subject.

Scanning from the TUI

1. From the scan list, press M (new email scan). If the credential store is locked you'll be prompted to unlock it first.
2. Fill in the server, username, and password. Alt+S toggles STARTTLS; Alt+C cycles through previously saved email accounts.
3. Optionally list folders to include (comma-separated) and adjust the throttle fields.
4. Press Enter to start. You land on the scan detail view with live progress.

Scanning from the CLI

export PIICRAWLER_IMAP_PASSWORD='your-app-password'
piicrawler imap imap.fastmail.com -u [email protected]

The CLI prints the saved scan's ID to stdout, so it chains into reports and triage:

SCAN_ID=$(piicrawler imap imap.fastmail.com -u [email protected] --quiet)
piicrawler report "$SCAN_ID"
piicrawler findings list --scan "$SCAN_ID"

Scan only some folders, or skip one:

piicrawler imap imap.fastmail.com -u [email protected] --folders INBOX,Archive
piicrawler imap imap.fastmail.com -u [email protected] --exclude-folder Newsletters

See CLI Reference for every flag.

What gets scanned inside a message

Each message is scanned as a complete email: headers (From, To, Cc, Subject), the text and HTML bodies, and every attachment, using the same extraction pipeline as file scans. A PDF or spreadsheet attached to a five-year-old email gets the same treatment as one sitting in a folder, including OCR for scanned documents and images (disable with the OCR option if you don't need it).

One caveat: .pst attachments (Outlook archive files, rare inside mail) are briefly written to a temporary file during extraction because the PST parser requires a file on disk. Every other format is processed fully in memory.

Being polite to your mail server

Mail providers limit how many IMAP connections a client may open (Gmail allows 15). PII Crawler opens at most one connection per fetch worker, which defaults to 2 concurrent fetches with a 100 ms delay between messages. That is gentle enough for any provider. If you are scanning your own mail server, you can raise the concurrency and drop the delay in the scan's performance options.

Rescanning

Every scan is a full pass over the selected folders. Messages that have not changed still benefit from the content cache within a scan, but there is no incremental "only new mail since last time" mode yet; it is on the roadmap along with OAuth sign-in.

Troubleshooting

• Authentication failed: double-check the username and confirm you are using an app password, not your account password. Gmail requires 2-Step Verification to be on before app passwords appear.
• Certificate verification failed: your server presented a certificate PII Crawler does not trust. On Linux and Windows, install the server's certificate (or your company's CA) into the OS trust store. On macOS, only publicly trusted certificate authorities are accepted, so use a mail server with a publicly issued certificate. PII Crawler intentionally has no option to skip certificate checks.
• Connection timed out: check the hostname and port, and whether the network between you and the server allows IMAP (some corporate networks block port 993/143 outbound).
• A folder shows as an error: your account lacks permission to open it (common with shared or system folders). The rest of the scan is unaffected; the folder is recorded in the files view so you know it was skipped.