warmbox/docs/08-spam-rescue-and-placement.md

Spam Rescue & Placement Tracking

Objectives

1. Detect when warmup emails land in spam/junk
2. Rescue them (move to inbox, positive signals)
3. Track spam rate per primary for dashboard and auto-pause
4. Never leave warmup mail unhandled in spam folders

Folder discovery

Default folder list (try in order)

Provider	Folders
Gmail	[Gmail]/Spam
Outlook	Junk
Yahoo	Bulk or Spam
Generic	Spam, Junk

Target enhancement

1. LIST IMAP folders on connect; match known spam patterns
2. Store per-mailbox spamFolderPath after first discovery
3. Provider enum shortcuts connection presets

Rescue workflow

sequenceDiagram
    participant R as Rescuer
    participant IMAP as Primary IMAP
    participant DB as Database

    R->>IMAP: Open spam folder
    R->>IMAP: SEARCH unseen FROM satellite
    IMAP-->>R: UIDs
    loop Each UID
        R->>IMAP: MOVE to INBOX
        R->>DB: Log placement=spam, status=rescued
        R->>IMAP: FLAGS Seen, Flagged
        R->>IMAP: FLAGS Important (best effort)
        R->>R: shouldReply?
        alt Reply sampled
            R->>SMTP: Send reply
        else No reply
            R->>DB: status=engaged_no_reply
        end
    end

Per-message matching (fix MVP weakness)

Current MVP marks all pending logs from sender when any spam found. Target:

Priority	Match key
1	Message-ID header exact match
2	In-Reply-To chain
3	From + normalized subject + 24h window

One UID → one WarmupLog row.

Placement tracking

Add to WarmupLog or separate PlacementEvent:

Field	Values
placement	inbox, spam, unknown
detectedAt	timestamp
rescuedAt	timestamp nullable
folder	string

Inbox placement rate

inboxRate = 1 - (spamDetected / totalReceived)

Target: ≥95% inbox after week 3.

INBOX processing (non-spam path)

Scan primary INBOX for unread warmup from assigned satellites:

• Same matching rules
• If already in inbox: flag + optional reply (no move)
• Log placement=inbox

Auto-pause triggers

Condition	Action
Spam rate >30% for 3 consecutive days	Pause campaign; alert operator
Spam rate >50% in 24h	Immediate pause
Rescue failures >5 in row	Mark primary error
Auth failure	Mark error; stop all jobs

Provider-specific notes

Gmail / Google Workspace

• \Important via labels (useLabels: true)
• Postmaster Tools integration (future): pull domain reputation
• App passwords required; OAuth preferred for SaaS

Microsoft 365 / Outlook

• Junk Email folder naming varies
• Enable IMAP in admin settings
• SNDS integration (future)

Yahoo

• App password required
• Bulk folder common

Compliance considerations

Rescue actions simulate user marking not spam — legitimate when acting on mail the user owns. Warmbox must only access mailboxes the operator controls.

Do not rescue mail the operator does not own (peer network phase requires explicit consent).

Future: seed placement tests

Optional inbox placement probes (like GlockApps) — out of MVP scope but document hook:

POST /campaigns/:id/placement-test → send test to probe addresses → report inbox/spam