Product Requirements Document: Unsubly (2026 Edition)

1. Executive Summary

Unsubly is a next-generation browser extension designed to reclaim user focus by decluttering inboxes. By leveraging modern email APIs and local-first processing, Unsubly identifies newsletters and subscription lists, provides frequency analytics, and enables secure, bulk one-click unsubscriptions. Built for the 2026 web ecosystem, it prioritizes user privacy, extreme performance (high INP scores), and seamless integration with Gmail and Outlook.

2. Problem Statement

Users in 2026 are overwhelmed by "digital noise." Despite smarter filters, the volume of marketing newsletters has increased, leading to:

• Cognitive Load: Manually identifying and unsubscribing from dozens of lists takes hours.
• Security Risks: Unused subscriptions are often entry points for data breaches.
• Productivity Loss: Important communications are buried under high-frequency promotional content.

3. Goals & Success Metrics

• Goal: Reduce time spent on manual inbox maintenance.
• Goal: Maintain a 100% privacy-first architecture where email content never leaves the client.
• Metrics:
  • Average Unsubscribes per User: Target 50+ in the first 7 days.
  • Dashboard Loading Time: < 500ms for 5,000+ detected subscriptions.
  • Active Retention: 40% of users performing a monthly "Cleanup Ritual."
  • Success Rate: > 95% successful unsubscriptions on first attempt.

4. User Personas

1. Alex, the Executive: Receives 300+ emails daily. Needs a "scorched earth" tool to clear the noise without risking sensitive data.
2. Jordan, the Digital Minimalist: Values clean interfaces and data privacy. Wants to know exactly which senders are "loudest."
3. Sam, the Student: Subscribed to hundreds of campus and tech newsletters over 4 years. Needs a bulk tool to reset their inbox for the professional world.

5. User Stories

• As a user, I want to link my Gmail and Outlook accounts securely so that I don't have to share my password.
• As a user, I want to see a list of my most frequent email senders so that I can decide who to remove first.
• As a user, I want to select 50 senders and click one button so that I can unsubscribe from all of them at once.
• As a user, I want to see the progress of my unsubscriptions in real-time so that I know the system is working.
• As a user, I want to ensure my email bodies are processed locally so that the company cannot read my personal messages.

6. Functional Requirements

6.1 Authentication & Security

• Multi-Provider OAuth: Support for Google and Microsoft via chrome.identity.
• PKCE Implementation: Mandatory Proof Key for Code Exchange for all auth flows.
• Encryption: Application-layer envelope encryption (AES-256-GCM) for all stored tokens.

6.2 Newsletter Detection Engine

• Header Analysis: Scans List-Unsubscribe and List-Unsubscribe-Post headers.
• Microsoft Graph Integration: Uses the 2026 unsubscribeEnabled and unsubscribeData properties.
• Frequency Logic: Calculates "Average Weekly Volume" and "Last Opened" metadata.

6.3 Dashboard & Interaction

• Side Panel UI: Primary interface hosted in the Chrome Side Panel for persistence.
• Bulk Actions: Multi-select checkboxes with a "Global Unsubscribe" trigger.
• Optimistic UI: Items fade/mark as "Pending" immediately upon action using React 19 useOptimistic.

6.4 Background Processing

• Task Queuing: Offloads heavy API calls to a background Service Worker.
• Rate Limiting: Intelligent batching (groups of 20) to stay within Google/Microsoft API quotas.

7. Technical Requirements

7.1 Tech Stack (2026 Standards)

• Frontend: React v19.2.x (with React Compiler 1.0), TypeScript, Tailwind CSS v4.1.x (Oxide engine).
• Extension Framework: Chrome Extension Manifest V3.
• Backend: Node.js v24 (Active LTS) with Fastify v5.7.x.
• Cloud Infrastructure: AWS Lambda (Durable Execution SDK) + API Gateway.
• Database:
  • Cloud: PostgreSQL 18+ (JSONB for encrypted payloads).
  • Local: SQLite over WASM + OPFS (Origin Private File System) for message indexing.
• Cache/Queue: ElastiCache Serverless (Redis Streams) + BullMQ.

7.2 Integrations

• Gmail API: Using format: metadata to minimize payload size.
• Microsoft Graph API (Beta): For enhanced mailing list schema properties.
• Sentry: For error monitoring within the Service Worker context.

8. Data Model

8.1 UserAccount (Cloud)

| Field | Type | Description | | :--- | :--- | :--- | | userId | UUID | Primary Key | | encryptedTokens | JSONB | IV, Tag, and Ciphertext (AES-256-GCM) | | provider | Enum | GMAIL, OUTLOOK | | lastSyncAt | Timestamp | Last header scan |

8.2 SubscriptionItem (Local SQLite)

| Field | Type | Description | | :--- | :--- | :--- | | senderEmail | String | Index Key | | displayName | String | Sender name | | weeklyFreq | Integer | Calculated volume | | unsubLink | String | Mailto or URL from header | | status | Enum | ACTIVE, PENDING, UNSUBSCRIBED |

9. API Specification

POST /api/v1/unsubscribe

• Description: Enqueues a bulk unsubscribe task.
• Request:

  {
    "provider": "GMAIL",
    "items": [
      { "id": "msg_123", "method": "LINK", "target": "https://..." },
      { "id": "msg_456", "method": "MAILTO", "target": "unsub@domain.com" }
    ]
  }
  

• Response: 202 Accepted with taskId.

10. UI/UX Requirements

• Virtualization: Use react-virtuoso for the subscription list to handle up to 10,000 items.
• Empty State: "Inbox Zero" illustration when no newsletters are detected.
• Feedback Loops: A global progress bar at the top of the side panel during bulk operations.
• Theme: Native-feel "System" theme (Dark/Light mode support).

11. Non-Functional Requirements

• Performance: INP (Interaction to Next Paint) must stay under 200ms.
• Privacy: No email body content may be sent to the backend. Only header metadata.
• Compliance: Must adhere to Google CASA Tier 2 security audit requirements.
• Availability: 99.9% uptime for the token refresh service.

12. Out of Scope

• Automatic deletion of old emails (Cleanup only, not archiving).
• Support for IMAP/POP3 (OAuth-only providers for Phase 1).
• Mobile application.

13. Risks & Mitigations

| Risk | Mitigation | | :--- | :--- | | Google/MS API Rate Limiting | Implement exponential backoff and BullMQ job retries. | | Restricted Scope Audit Cost | Budget $15k for initial CASA Tier 2 assessment. | | Service Worker Hibernation | Use chrome.alarms to wake workers for long-running syncs. | | User Privacy Concerns | Implement Local-First architecture; processing happens in-browser. |

14. Implementation Tasks

Phase 1: Project Setup & Auth

• [ ] Initialize React 19.2 project with Vite 6 and Tailwind 4.1
• [ ] Set up Manifest V3 boilerplate with Side Panel API
• [ ] Implement chrome.identity OAuth 2.0 flow with PKCE
• [ ] Configure Fastify 5.7 backend with AWS Lambda adapter
• [ ] Set up PostgreSQL 18 schema with AES-256-GCM encryption utilities

Phase 2: Email Discovery Engine

• [ ] Build local indexing layer using SQLite WASM + OPFS
• [ ] Implement Gmail API metadata fetcher (format: metadata)
• [ ] Implement Microsoft Graph fetcher for unsubscribeEnabled
• [ ] Create heuristic parser for List-Unsubscribe headers
• [ ] Develop frequency calculation algorithm (local Web Worker)

Phase 3: Dashboard & Virtualization

• [ ] Build Subscription List UI using react-virtuoso
• [ ] Implement search and "Sort by Frequency" functionality
• [ ] Integrate React 19 useOptimistic for item selection states
• [ ] Design and implement the Chrome Side Panel entry point

Phase 4: Bulk Unsubscribe Logic

• [ ] Create backend task producer using BullMQ and Redis Streams
• [ ] Implement MAILTO unsubscribe handler (automatic email drafting/sending)
• [ ] Implement URL unsubscribe handler (background fetch)
• [ ] Build real-time progress tracker via WebSockets or Long Polling
• [ ] Add "Soft Rollback" logic for failed unsubscription attempts

Phase 5: Compliance & Polishing

• [ ] Conduct internal DAST scan for OWASP vulnerabilities
• [ ] Finalize "Limited Use" Privacy Policy and Google Brand Verification
• [ ] Implement "Undo" buffer (5-second delay before task execution)
• [ ] Set up Sentry error tracking for Service Workers
• [ ] Add Dark Mode support via Tailwind 4.1 @theme system