MailSearch support

Help and frequently asked questions · Last updated 22 May 2026

What is MailSearch?

MailSearch is a local-first macOS app that lets you search every email you’ve ever received, across every mailbox you connect to it. It indexes your mail on your Mac — subjects, senders, recipients, body text, plus text extracted from PDF / RTF / plain-text attachments — and answers searches in milliseconds. Tokens stay in your Keychain; mail flows directly from your provider to MailSearch with no Whiteforge servers in the path.

MailSearch is a search engine + read-only viewer. It does not reply, send, archive, delete, or modify your mailbox in any way.

Is MailSearch stable? What does beta mean here?

MailSearch is in public beta. The four mail providers (Gmail, Outlook, iCloud, generic IMAP) are all wired end-to-end and tested against real mailboxes; the local search index uses SQLite’s FTS5 (which has been stable since 2015). The beta status reflects:

• Limited real-world exposure across the universe of weird MIME / RTF / encoded-word forms in the wild.
• Incremental sync isn’t wired yet — each Sync now fetches the most recent 500 messages from scratch (de-duplicated against the existing index, so re-running is cheap, but new mail since the last sync is what you’ll see).
• Full HTML body rendering inside the viewer hasn’t landed yet — the message-detail panel shows the matching snippet and the plain-text body.

How does the search work?

MailSearch uses SQLite’s FTS5 full-text search over five indexed columns per message: subject, sender, recipients, body text (up to 50 KB), attachment text (up to 20 KB). Your query is split into words and treated as AND-with-prefix:

• AND semantics: every word you type must appear in the matched message. amazon refund matches a message that contains both “amazon” and “refund”.
• Prefix matching: each word is treated as a prefix, so invoi matches “invoice” and anders matches “Anderson”.
• No fuzzy match, no synonyms. If the word isn’t in the message exactly (or as a prefix), the message won’t match.

How do I connect a Gmail account?

Open MailSearch, find the sidebar on the left, click + Add Gmail. Your default browser opens to Google’s consent screen. The first time you connect, you may see a yellow “Google hasn’t verified this app” warning — that’s expected for a desktop app in early use. Click Advanced → Go to MailSearch Desktop (unsafe) to proceed (it’s the same OAuth client that owns the scope you’re granting). Grant the read-only Gmail scope; the browser tab redirects to a small “you can close this” page, and the sidebar shows your account.

MailSearch only requests gmail.readonly — no ability to send, reply, archive or delete.

How do I connect an Outlook / Microsoft 365 account?

Same flow as Gmail: + Add Outlook in the sidebar opens Microsoft’s consent page in your browser. Grant the requested scopes (Mail.Read, User.Read, offline_access), the browser redirects back, the sidebar shows your account.

How do I connect iCloud Mail?

Apple doesn’t support OAuth for iCloud Mail, so you’ll need an app-specific password (your regular Apple ID password won’t work):

1. Open appleid.apple.com and sign in.
2. Sign-In and Security → App-Specific Passwords.
3. Generate a new password labelled MailSearch. Apple shows it once — copy it.
4. In MailSearch, click + Add iCloud Mail, enter your full iCloud email + paste the 16-character app-specific password.

MailSearch validates the credentials by opening an IMAP session + LOGIN + SELECT INBOX before saving anything. If those three succeed, the password lands in your Keychain; if any fail, nothing is saved.

How do I connect a generic IMAP mailbox?

Click + Add IMAP, fill in: email address, IMAP server (e.g. mail.btinternet.com, imap.fastmail.com), port (usually 993), and your password. If your provider requires an app-specific password (most do once 2FA is on), generate one in their settings first.

How much of my mail does MailSearch index?

v0.1.0 indexes the most recent 500 messages per mailbox per Sync now. The cap is conservative for a first release; incremental sync + a higher per-run cap arrive in a follow-up.

Re-running Sync now on the same mailbox is cheap: messages already in the index with byte-identical contents are skipped at insert time, bypassing the FTS triggers entirely.

Are attachments searchable?

Yes, for three formats: PDF, RTF and plain text (.txt / .log / .md). Image / video / archive / binary attachments are skipped because there’s no text payload to index cheaply. Per-attachment cap: 5 MB (larger ones get skipped at fetch time); per-message attachment text cap: 20 KB.

Where is my data stored?

• Local index + body cache: ~/Library/Application Support/uk.co.whiteforgetech.mailsearchmac/mailsearchmac.db.
• Connected-account list: accounts.json in the same directory. Contains email + provider kind + IMAP host. No tokens, no passwords.
• Tokens / IMAP passwords: macOS Keychain.

See the privacy policy for the full detail. Whiteforge servers see none of this — mail flows directly from your provider to your Mac.

System requirements

• macOS 11 (Big Sur) or later.
• Apple Silicon (M1+) or Intel.
• Around 200 MB of free disk space, plus space for the index (typically 5–50 MB per 500 messages depending on attachment sizes).

How do I download the beta?

Download the disk image matching your Mac’s processor:

• MailSearchMac-aarch64.dmg — Apple Silicon.
• MailSearchMac-x86_64.dmg — Intel Macs.

Both disk images are signed with our Developer ID Application certificate and notarized by Apple.

How do I install it?

1. Double-click the .dmg to open it.
2. Drag MailSearch into Applications.
3. Eject the disk image.
4. Launch MailSearch from Applications.

What happens on first launch?

macOS will show a confirmation dialog the first time you open it (“MailSearch is an app downloaded from the internet. Apple checked it for malicious software and none was detected.”). Click Open. The app shows a one-time welcome modal; close it, then click any of the + Add buttons in the sidebar to connect a mailbox.

macOS keeps prompting me for my password

When MailSearch first reads a token / password from your Keychain after a fresh install or update, macOS asks you to confirm. Click Always Allow (not Allow) to make the trust persistent — Allow grants one-shot access only and you’ll be re-prompted next sync.

If you ever update MailSearch and the prompt comes back, that’s because the new binary’s code signature differs — Always Allow the new one and you’re set until the next update.

How do I report a bug?

Two channels:

• Public Issue tracker at github.com/whiten1968/MailSearchMac-downloads/issues. Faster for us to triage. Don’t attach actual emails here — it’s a public repository.
• Email support@whiteforgetech.co.uk for anything you’d rather keep private.

Either way, please include: what you were doing, what you expected, what actually happened, your macOS version, the MailSearch version (Settings → bottom of the panel).

How do I request a feature?

Open a Discussion on the downloads repo, or email support@whiteforgetech.co.uk.

Contact

Whiteforge Technologies Ltd
support@whiteforgetech.co.uk

Back to MailSearch overview →