WarmupFlow

Productivity

Original Idea

Email Warmup Planner A background service that ramps volume, pauses on bounces, and reports inbox health.

Product Requirements Document (PRD): WarmupFlow

1. Executive Summary

WarmupFlow is a background-as-a-service platform designed to automate email deliverability optimization. By simulating human-like behavior, managing gradual volume ramping, and providing real-time inbox health monitoring, WarmupFlow ensures that new or "cold" email domains build a positive sender reputation. The platform handles the complexity of OAuth2 authentication, provider-specific rate limiting, and automated engagement (replies, stars, spam-to-inbox moves) to keep users out of the spam folder and in the primary inbox.

2. Problem Statement

New email domains and accounts suffer from "cold" reputations, leading to immediate spam filtering by ISPs like Google and Microsoft. Manual warm-up—sending a few emails a day and asking friends to reply—is unscalable and prone to error. If a user ramps volume too quickly or ignores high bounce rates, they face permanent domain blacklisting. Existing tools often use static, robotic patterns that modern AI-driven spam filters in 2026 easily detect and penalize.

3. Goals & Success Metrics

  • Target Deliverability: Achieve >98% inbox placement for warmed accounts within 30 days.
  • Automation Efficiency: Reduce manual deliverability management time by 95% for SDR/BDR teams.
  • Health Recovery: Successfully move 80% of "flagged" domains back to "healthy" status using automated spam-to-inbox interaction.
  • Retention: Maintain <5% monthly churn for agencies managing 50+ inboxes.

4. User Personas

  • Sam the SDR: Needs to ensure his 50 daily cold emails actually reach prospects' primary inboxes.
  • Founding Fiona: Launching a new SaaS on a fresh .com domain and needs to build reputation from scratch without technical overhead.
  • Agency Alex: Manages 200+ inboxes for 20 clients; requires a centralized dashboard to monitor "health" and auto-pause failing campaigns.

5. User Stories

  • As a Marketer, I want to connect my Google Workspace account via OAuth so that I don't have to manage insecure app passwords.
  • As an SDR, I want the system to automatically move my emails from the spam folder to the primary inbox so that ISPs learn my content is valuable.
  • As a Founder, I want a "Staircase" ramping schedule that increases my volume by 2-5 emails daily so I don't trigger "suspicious activity" alerts.
  • As an Agency Owner, I want to receive a Slack alert if any of my clients' domains hit a bounce rate higher than 5% so I can intervene immediately.

6. Functional Requirements

6.1 Email Integration & Authentication

  • OAuth2 Flow: Full integration with Google Cloud (CASA Tier 2/3 compliant) and Microsoft Graph API (M365 Certified).
  • SMTP/IMAP Fallback: Support for custom providers (Zoho, iCloud, etc.) with manual configuration.

6.2 Automated Warmup Engine

  • Linear-Staircase Ramping: Automated logic starting at 5-10 emails/day, increasing by a configurable linear increment (e.g., +2/day) up to a 50-email cap.
  • AI Engagement Loops: Generate human-like reply chains using LLM-based content to ensure a 30-45% reply-to-send ratio.
  • Inbox Actions: Automated "Starring," marking as "Important," and "Spam-to-Inbox" movement.

6.3 Monitoring & Safety

  • Real-time Bounce Guard: Immediate auto-pause of all sending if hard bounces exceed 3% in a 24-hour window.
  • Reputation Scoring: A 0-100 "Health Score" based on SPF/DKIM/DMARC status, blacklist presence, and historical deliverability.

6.4 Reporting

  • Deliverability Heatmap: Breakdown of placement (Primary, Promotions, Spam) across Gmail vs. Outlook.

7. Technical Requirements

7.1 Tech Stack (2026 Versions)

  • Frontend: Next.js v16.1.3 (Turbopack enabled) with Tailwind CSS v4.1.18 (Oxide Engine).
  • Backend: Node.js v24.13.0 (Active LTS) utilizing AsyncContextFrame for task tracing.
  • Worker Queue: BullMQ v5.66.5 for distributed job processing.
  • Database: PostgreSQL 18 (using native uuidv7() for time-ordered logging).
  • Cache/Queue Storage: Redis 7.4 (or Dragonfly) for high-concurrency job management.
  • Infrastructure: AWS ECS (Fargate) for auto-scaling workers based on "Active Account" metrics.

7.2 Integrations

  • Google Workspace API: Restricted scopes (/auth/gmail.modify).
  • Microsoft Graph API: Mail.ReadWrite permissions via OAuth 2.0.
  • Postmaster/SNDS: Integration with provider health tools.
  • Slack/Discord: Webhook-based alerting for health drops.

8. Data Model

8.1 EmailAccount

  • id: UUIDv7 (Primary Key)
  • userId: UUIDv7 (FK)
  • email: String (Encrypted at rest)
  • provider: Enum (GMAIL, OUTLOOK, SMTP)
  • credentials: JSONB (Encrypted OAuth tokens)
  • status: Enum (CONNECTED, REJECTED, PAUSED)

8.2 WarmupSchedule

  • id: UUIDv7
  • accountId: UUIDv7 (FK)
  • dailyLimit: Integer (Current target)
  • incrementRate: Integer (Emails to add per day)
  • maxVolume: Integer (Hard cap, default 50)
  • lastSentAt: Timestamp

8.3 EmailLog (Time-Series Partitioned)

  • id: UUIDv7
  • accountId: UUIDv7
  • messageId: String
  • direction: Enum (SENT, RECEIVED)
  • status: Enum (DELIVERED, BOUNCED, SPAM, OPENED)
  • providerFeedback: JSONB
  • partitionKey: Date (Daily partitioning)

9. API Specification

| Endpoint | Method | Description | | :--- | :--- | :--- | | /api/v1/auth/google | GET | Initiates OAuth2 flow for Gmail | | /api/v1/accounts | POST | Connects an account (SMTP/IMAP or OAuth) | | /api/v1/warmup/start | PATCH | Activates the staircase logic for an account | | /api/v1/health/:id | GET | Returns reputation score and heatmap | | /api/v1/webhooks/bounce | POST | Ingests bounce notifications from ESPs |

10. UI/UX Requirements

  • Dashboard: High-level overview of "Healthy" vs "At Risk" inboxes using a traffic-light color system.
  • Account Setup Wizard: A 3-step process (Connect -> Configure Ramping -> Verify DNS).
  • Heatmap Component: A 7-day grid showing "Inbox vs. Spam" placement for major providers.
  • Responsive Design: Mobile-first dashboard for SDRs to check health on the go.

11. Non-Functional Requirements

  • Performance: Background workers must handle 10,000+ concurrent SMTP connections using pool: true and idle events.
  • Security: AES-256 encryption for all stored credentials; strict compliance with Google/Microsoft "Limited Use" policies.
  • Scalability: ECS Auto-scaling ratio of 1 task per 50 active warmup accounts.
  • Availability: 99.9% uptime for the background worker service to ensure warmup schedules are not interrupted.

12. Out of Scope

  • Bulk Marketing Sender: WarmupFlow is NOT a replacement for Mailchimp/SendGrid; it is for warmup and reputation maintenance only.
  • CRM Features: No lead management or pipeline tracking.
  • Domain Purchasing: We do not sell domains; users must bring their own.

13. Risks & Mitigations

  • Risk: Google/Microsoft update AI filters to block WarmupFlow IPs.
    • Mitigation: Implement a Peer-to-Peer (P2P) network where users' inboxes send to each other, rotating residential/corporate IP footprints.
  • Risk: OAuth token expiration or revocation.
    • Mitigation: Proactive token refresh logic and immediate UI/Email notifications for "Account Disconnected" events.
  • Risk: High database costs due to EmailLogs.
    • Mitigation: Implement 30-day retention with Daily Partitioning; archive logs older than 30 days to S3/Cold Storage.

14. Implementation Tasks

Phase 1: Project Setup

  • [ ] Initialize Next.js 16.1.3 project with Turbopack
  • [ ] Configure Tailwind CSS 4.1.18 with Oxide engine
  • [ ] Set up PostgreSQL 18 with pg_partman for Daily Partitioning
  • [ ] Initialize BullMQ 5.66.5 with Redis 7.4 connection

Phase 2: Authentication & Core Engine

  • [ ] Implement Google OAuth2 flow (CASA-compliant Restricted Scopes)
  • [ ] Implement Microsoft Graph API OAuth flow (M365 certified)
  • [ ] Create AES-256 encryption utility for credential storage
  • [ ] Develop SMTP Pooled Transport with idle event handling

Phase 3: Warmup Logic & Workers

  • [ ] Build the "Safe Staircase" algorithm (linear increments)
  • [ ] Implement BullMQ "Virtual Grouping" for provider-aware rate limiting
  • [ ] Create "Spam-to-Inbox" worker using ImapFlow
  • [ ] Integrate LLM API for dynamic reply-chain content generation

Phase 4: Dashboard & Reporting

  • [ ] Build Reputation Score dashboard (Next.js Server Components)
  • [ ] Implement real-time health alerts via Slack Webhooks
  • [ ] Create "Deliverability Heatmap" UI component
  • [ ] Set up AWS ECS Fargate auto-scaling based on active accounts

Phase 5: Security & Compliance

  • [ ] Complete CASA Tier 2 security self-assessment documentation
  • [ ] Implement DMARC/SPF/DKIM verification checker
  • [ ] Set up UUIDv7 primary keys across all tables for PG 18 optimization
  • [ ] Perform load test with 5,000 simulated concurrent email tasks