How Post Guard AI Works

1. New Mail Detected

Post Guard AI supports three detection methods depending on your connection type:

On initial connection, all existing unread messages are processed first so that emails which arrived while the monitor was offline are still classified. Gmail API monitors use adaptive polling that doubles the interval (30 s → 1 min → 2 min → 5 min) after each empty cycle and resets to 30 s when new messages arrive — cutting idle API usage by over 90%. When a Google Cloud Pub/Sub topic is configured, push notifications wake the monitor instantly; polling is retained as a safety net in case a push is lost. The Pub/Sub watch is automatically renewed before its 7-day expiry. If the connection to the mail server is lost, the monitor reconnects automatically with exponential backoff (2 s → 4 s → … → 2 min max). If authentication fails (bad password, revoked OAuth token, missing OAuth credentials), the mailbox is automatically disabled to prevent retry loops — update the credentials in the Mailbox Manager to resume.

2. Batch Pre-Filter

Before any expensive work begins, two bulk queries run concurrently against PostgreSQL:

• Processed message IDs — every message ID already classified for this mailbox is loaded into a HashSet.
• Whitelisted domains — the mailbox-level and owner-level domain whitelists are merged into a single HashSet.

This replaces the previous per-message approach (2×N individual DB queries) with just 2 queries per batch. Messages whose MIME Message-ID already appears in the processed set are skipped immediately — before fetching content, scanning attachments, or calling the AI. Whitelisted senders are allowed through without classification.

3. Attachment Virus Scan

Every attachment is streamed to ClamAV for malware detection via a shared, singleton ClamAV client — eliminating per-attachment connection overhead. If a virus is found, the email is immediately flagged and moved to the quarantine folder. No further processing occurs.

4. Parallel AI Classification

Messages that pass the pre-filter and virus scan enter the AI classification stage. Up to 2 messages are classified concurrently per server using a semaphore-controlled parallelism strategy, matching the number of GPU instances to prevent VRAM exhaustion and CPU fallback. When multiple Ollama servers are configured, requests are distributed across them via random selection for additional throughput.

The message subject, sender, classification-relevant headers, and body are assembled into a structured prompt. Only headers that influence classification (SPF, DKIM, List-Unsubscribe, etc.) are included — reducing prompt size by approximately 80%. When the email has no plain-text part (common with marketing templates from Spotify, Amazon, etc.), the raw HTML is stripped to clean text using HtmlAgilityPack — removing <style>, <script>, and comment nodes, decoding HTML entities, and collapsing whitespace so the AI sees the actual content rather than thousands of characters of markup noise. Email bodies are then truncated to 12,000 characters to stay within the 16,384-token context window (after reserving space for the system prompt), with a truncation indicator appended so the AI knows the content is incomplete.

The classification system prompt is maintained as a dedicated, version-controlled constant — separate from the classification logic — so it can be reviewed, diffed, and updated independently. The prompt is sent to the cloud-hosted Ollama LLM via Microsoft Semantic Kernel . The model returns a JSON classification containing the category, risk level, confidence score, and recommended action.

5. User Preference Matching

The classification result is compared against your per-mailbox preferences (cached once per connection to avoid per-message DB calls). For example, if you allow newsletters but block promotions, a message classified as NEWSLETTER stays in your inbox while a PROMOTIONAL message is moved.

6. Action — Allow or Move

Allow: The message remains in your inbox untouched.
Block: The message is moved to a folder determined by its classification category. Each category (Newsletter, Promotional, Advertising, Selling, Spam, Virus, Unknown) can be routed to a different IMAP folder or Gmail label — configured per-account on the Settings page. All categories default to Promotions for a simple out-of-the-box experience.

IMAP move operations are serialised (IMAP connections are single-threaded) even when classification runs in parallel. If you disagree with a classification, simply drag the email back to your inbox. Post Guard AI detects the banner and automatically whitelists that sender's domain for future messages.