System Requirements Document for webmail-bulk-email

1. Introduction

webmail-bulk-email is a self-service webmail product for sending one message to many recipients at once and having those messages land in recipients' inboxes rather than spam or bulk folders. The product is built for senders — marketers, small operations teams, and community organisers — who judge the tool by what happens after they press send, and who want to see the delivery machinery (routing, authentication, queue, inbox placement) rather than a friendly marketing gloss.

The product's intent is trust through transparency: a composed message on one side, the machine that delivers it on the other. Senders enroll themselves, build and maintain recipient sets, author a bulk message with a subject and body, dispatch it in one operation, and then review delivery outcomes to confirm inbox placement.

This document is the System Requirements Document for the product; it specifies the current delivery, its actors, its pages, its functional requirements, and its design direction.

2. System Overview

2a. Product Interpretation and Delivery Boundary

webmail-bulk-email is delivered as a first-party web application with a custom React front end, a shared FastAPI backend, and a MariaDB database for application-owned persistent data. All product surfaces — Landing, Sign Up, Login, Compose, Recipients, and Delivery Reports — are owned and rendered by the application.

Identity is application-owned. A sender establishes identity through self-service Sign Up and verifies returning identity through Login. Landing, Sign Up, and Login are anonymously reachable; Compose, Recipients, and Delivery Reports require a logged-in sender and are protected. There is no differentiated permission model: every authenticated sender sees and works with their own recipient sets, sends, and delivery reports.

Recipients are external actors. They receive bulk-sent messages in their own inboxes through the delivery machinery; they do not use the product's interface. The product's promise — inbox, not spam — is realized by the delivery pipeline and made observable to the sender through Delivery Reports.

Current scope is limited to: self-service enrollment and login, recipient-set management, bulk message composition and dispatch, and delivery-outcome review. No adjacent capabilities (campaign scheduling, template libraries, analytics beyond delivery outcomes, team collaboration, billing) are part of the current product.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous public entry. Explains the bulk webmail product, its audience, and its capabilities before identity establishment. Presents the split-screen hero: warm paper half with the composed-message/human side, ink-dark half with the delivery machinery (queue rows, authentication checks, inbox-placement meter).
• Primary actions: "Start sending" (burnt-orange text link) leading to Sign Up; navigation to Login for returning senders.
• Supporting actions: Hover on the split seam or envelope SVG toggles wireframe-to-solid rendering.
• Domain entities: None persisted; presents product capability and delivery concepts (queue, SPF/DKIM checks, inbox placement).
• Component responsibilities: Hero split (7/5 desktop, stacked under 768px with dark panel as bordered inset card); oversized Space Grotesk headline "Send to many. Land in the inbox."; 11px uppercase micro-label "BULK WEBMAIL / INBOX DELIVERY"; live delivery panel with stacked recipient rows in IBM Plex Mono, orange status dots, "99.2% inbox placement" numeral, wireframe envelope SVG; 2px orange seam rule running off top and bottom edges.
• States: Loading (static hero, no data dependency); empty (not applicable — static marketing content); success (hero renders, links active); error (not applicable); recovery (reduced-motion: static arrangement, seam rule stays put).

Sign Up

• Information/state: Anonymous first-use enrollment surface for a sender who independently begins using the product. Collects the sender's identifying credentials to create an application-owned account.
• Primary actions: Submit enrollment to create the sender's account and establish a session.
• Supporting actions: Navigate to Login if already enrolled.
• Domain entities: Sender account (identity, credentials).
• Component responsibilities: Enrollment form with sharp 2px-corner inputs and 1px hairline borders; monospace metadata strip; inline validation messaging; submit control.
• States: Loading (submit in progress); empty (blank form); success (account created, sender proceeds to protected work); error (invalid or incomplete input, duplicate identity — inline message with recovery); recovery (correct input and resubmit).

Login

• Information/state: Anonymous returning-verification surface for senders to reach their protected recipient lists, sends, and delivery reports.
• Primary actions: Submit credentials to verify identity and establish a session.
• Supporting actions: Navigate to Sign Up if not yet enrolled.
• Domain entities: Sender account (identity, credentials).
• Component responsibilities: Credential form with sharp 2px-corner inputs; inline error messaging; submit control.
• States: Loading (verification in progress); empty (blank form); success (session established, sender reaches protected destinations); error (invalid credentials — inline message with recovery); recovery (re-enter credentials and resubmit).

Compose

• Information/state: Protected focused owner for authoring a bulk message with subject and body and dispatching it to the selected recipients in one operation. Persistent left rail (compose/recipients/reports) against a wide working canvas; dark technical panel reused as a persistent component.
• Primary actions: Author subject and body; select the recipient set; dispatch the bulk send.
• Supporting actions: Navigate to Recipients to manage the recipient set; navigate to Delivery Reports to review outcomes.
• Domain entities: Bulk message (subject, body), recipient set, send record.
• Component responsibilities: Message editor (warm paper surface, white card); recipient-set selector; dark technical panel with queue rows, DKIM/SPF check rows, inbox-placement meter in IBM Plex Mono with orange status dots; monospace metadata strip ("FROM / DOMAIN / RECIPIENTS / QUEUE"); single orange send CTA.
• States: Loading (recipient sets loading); empty (no recipient set selected — prompt to choose or create one); success (send dispatched, confirmation and link to Delivery Reports); error (missing subject/body/recipients, dispatch failure — inline message with recovery); recovery (correct input or retry dispatch).

Recipients

• Information/state: Protected, independently revisitable owner for specifying and managing the recipient set used in bulk sends. Persistent left rail against a wide working canvas.
• Primary actions: Add recipients to a set; create and name a recipient set; edit or remove recipients.
• Supporting actions: Navigate to Compose to use the set in a send.
• Domain entities: Recipient set, recipient (address).
• Component responsibilities: Recipient-set list; recipient entry with sharp 2px-corner inputs; dashed-outline drop targets; monospace metadata strip; save/remove controls.
• States: Loading (sets loading); empty (no sets yet — prompt to create one); success (set saved, recipients listed); error (invalid address, save failure — inline message with recovery); recovery (correct entry and resave).

Delivery Reports

• Information/state: Protected owner for reviewing the outcome of bulk sends, including whether messages reached recipients' inboxes. Persistent left rail against a wide working canvas; dark technical panel reused as a persistent component.
• Primary actions: Review send outcomes and inbox-placement results per send.
• Supporting actions: Navigate to Compose to send again; navigate to Recipients to adjust sets.
• Domain entities: Send record, delivery outcome, inbox-placement result.
• Component responsibilities: Send history list; per-send delivery detail with queue rows, DKIM/SPF check rows, and inbox-placement meter in IBM Plex Mono with orange status dots; count-up numerals on scroll into view.
• States: Loading (reports loading); empty (no sends yet — prompt to compose a send); success (outcomes displayed); error (report load failure — inline message with retry); recovery (retry load).

3. Functional Requirements

FR-1 — Bulk send from webmail interface (explicit) As a Bulk Email Sender, I should send one email to many recipients at once from a webmail interface, so that I can reach my audience in a single operation.

• Trigger/input: authenticated sender authors subject and body on Compose and selects a recipient set.
• Observable result: the bulk send is dispatched and a send record is created.
• Access: login required.
• Failure/recovery: missing subject, body, or recipients blocks dispatch with an inline message; dispatch failure surfaces an inline error and allows retry.
• Continuation: sender proceeds to Delivery Reports to review outcomes.

FR-2 — Inbox delivery intent (explicit) As a Bulk Email Sender, I should have bulk-sent email delivered to recipients' inboxes rather than spam or bulk folders, so that my messages are actually seen.

• Trigger/input: a dispatched bulk send.
• Observable result: delivery outcomes recorded and shown on Delivery Reports, including inbox placement.
• Access: login required (sender); recipient receives externally.
• Failure/recovery: outcomes that do not reach the inbox are visible in Delivery Reports so the sender can see the result.
• Continuation: sender reviews outcomes and may send again.

FR-3 — Self-service enrollment (required_inference) As a Bulk Email Sender, I should complete self-service enrollment via Sign Up, so that I can begin using the product independently.

• Trigger/input: anonymous visitor selects "Start sending" on Landing.
• Observable result: sender account created and session established.
• Access: none (anonymous).
• Failure/recovery: invalid or incomplete input shows inline error; sender corrects and resubmits.
• Continuation: sender reaches protected destinations.

FR-4 — Returning identity verification (required_inference) As a Bulk Email Sender, I should verify my returning identity via Login, so that I can reach my protected recipient lists, sends, and delivery reports.

• Trigger/input: returning sender submits credentials on Login.
• Observable result: session established; protected destinations reachable.
• Access: none (anonymous entry).
• Failure/recovery: invalid credentials show inline error; sender re-enters and resubmits.
• Continuation: sender proceeds to Compose, Recipients, or Delivery Reports.

FR-5 — Recipient set management (required_inference) As a Bulk Email Sender, I should specify and manage the recipient set used in bulk sends, so that a send has a defined audience.

• Trigger/input: authenticated sender adds recipients and creates/named a set on Recipients.
• Observable result: recipient set persisted and available for selection on Compose.
• Access: login required.
• Failure/recovery: invalid address or save failure shows inline error; sender corrects and resaves.
• Continuation: sender selects the set on Compose.

FR-6 — Dispatch before outcome review (required_inference) As a Bulk Email Sender, I should dispatch a bulk send before delivery outcomes can be reviewed, so that Delivery Reports reflect actual sends.

• Trigger/input: sender dispatches from Compose.
• Observable result: send record created; outcomes appear on Delivery Reports.
• Access: login required.
• Failure/recovery: dispatch failure surfaces inline error and allows retry.
• Continuation: sender reviews outcomes on Delivery Reports.

FR-7 — Recipient receives in inbox (required_inference) As an Email Recipient, I should receive bulk-sent messages in my inbox rather than spam or bulk folders, so that the sender's message reaches me.

• Trigger/input: a dispatched bulk send addressed to the recipient.
• Observable result: message arrives in the recipient's inbox.
• Access: external (recipient's own mailbox).
• Failure/recovery: misplacement is reflected in the sender's Delivery Reports.
• Continuation: recipient reads the message in their inbox.

4. User Personas

Bulk Email Sender

• Product context: A marketer, small operations team member, or community organiser who needs many messages to land in inboxes, not spam folders. Judges the tool by what happens after pressing send and wants to see the delivery machinery.
• Primary goal: Compose and send email to many recipients at once from a webmail interface and have those messages land in recipients' inboxes.
• Distinct accepted responsibilities: Self-service enrollment via Sign Up; returning verification via Login; managing recipient sets on Recipients; authoring subject and body and dispatching on Compose; reviewing delivery outcomes on Delivery Reports.
• Relevant inputs/decisions: Recipient addresses and set composition; message subject and body; recipient-set selection for a send; interpretation of delivery outcomes.
• Interactions with other participants: Sends to Email Recipients, whose inbox arrival defines the sender's success; reviews outcomes that reflect recipient-side delivery.
• Observable success: A dispatched bulk send whose Delivery Reports show messages reached recipients' inboxes.

Email Recipient

• Product context: Receives bulk-sent messages in their own inbox; the sender's success is defined by messages arriving in this recipient's inbox rather than spam or bulk folders.
• Primary goal: Receive the sender's bulk-sent message in the inbox.
• Distinct accepted responsibilities: Receiving dispatched messages in the inbox; the placement outcome is what the sender reviews.
• Relevant inputs/decisions: None within the product interface; the recipient acts in their own mailbox.
• Interactions with other participants: Receives from the Bulk Email Sender; their inbox placement is reflected in the sender's Delivery Reports.
• Observable success: The message appears in the recipient's inbox.

5. Core User Flows

Flow A — First-time sender enrolls and sends a bulk message

1. Anonymous visitor lands on Landing and reads the product explanation and delivery panel.
2. Visitor selects "Start sending" and arrives at Sign Up.
3. Sender submits enrollment; on success an account is created and a session established. On invalid input, an inline error appears and the sender corrects and resubmits.
4. Sender arrives at Recipients and creates a named recipient set, adding recipient addresses. On invalid address or save failure, an inline error appears and the sender corrects and resaves.
5. Sender moves to Compose, authors subject and body, and selects the recipient set.
6. Sender presses the orange send CTA. On missing subject/body/recipients or dispatch failure, an inline error appears and the sender corrects or retries.
7. On success, the send is dispatched and a send record is created; the sender is offered a link to Delivery Reports.
8. Sender opens Delivery Reports and reviews the send's outcomes, including inbox placement. If no sends exist yet, an empty state prompts composing a send.

Flow B — Returning sender logs in and sends

1. Returning sender arrives at Login and submits credentials.
2. On success, a session is established and protected destinations become reachable. On invalid credentials, an inline error appears and the sender re-enters and resubmits.
3. Sender opens Recipients to review or adjust the recipient set.
4. Sender opens Compose, authors the message, selects the set, and dispatches.
5. Sender opens Delivery Reports to review outcomes.

Flow C — Sender reviews delivery outcomes

1. Authenticated sender opens Delivery Reports.
2. Sender selects a send from the history.
3. Sender reviews queue rows, DKIM/SPF check rows, and the inbox-placement meter; numerals count up once on scroll into view.
4. If reports fail to load, an inline error appears and the sender retries.
5. Sender may return to Compose to send again or Recipients to adjust sets.

Flow D — Recipient receives the message

1. A bulk send is dispatched from Compose.
2. The delivery machinery routes the message to the recipient's mailbox.
3. The Email Recipient receives the message in their inbox rather than spam or bulk folders.
4. The placement outcome is reflected in the sender's Delivery Reports.

6. Visuals Colors and Theme

Muse: Adham Dannaway. Headline: "Send to many. Land in the inbox."

Palette (light mode):

• Background: #F7F5F0 (warm paper ground)
• Surface: #FFFFFF (cards, message editor)
• Text / primary: #14161A (deep ink)
• Accent: #E4572E (burnt orange — the only hot colour)
• Muted: #6B6F76 (metadata, helper text)

Dark technical panel: ink #14161A ground with #F7F5F0 text and #E4572E signal accents for queue states, verification ticks, and the send CTA.

Contrast: ink on paper ≈ 15:1; orange on ink ≈ 5.1:1 at large sizes, reserved for labels ≥16px semibold; body copy never orange on paper.

Typography:

• Headings: Space Grotesk, 500–700, tight tracking (-0.02em), sentence case for display headlines, uppercase 11–12px letterspaced micro-labels over the dark technical panel.
• Monospace voice: IBM Plex Mono for addresses, domains, DKIM strings, and delivery numbers.
• Body: IBM Plex Sans.
• Scale (1.333 modular): display clamp(56px, 8vw, 104px); h2 32/44; h3 22/28; body 16/18; micro-label 11/12 uppercase +0.12em; mono data 13/14. Line-height 1.05 on display, 1.6 on body.

Shape language: Precise 8-pt geometry with a hard vertical split as the organising motif. Sharp 2px corners on panels and inputs (no pill buttons); 1px hairlines in #14161A at 12% opacity; a single 2px orange rule down the split seam on the hero. Small details: a tiny wireframe-to-solid toggle, a caret-style cursor block in the mono panel, dashed outlines on drop targets.

Layout: Split-screen primary structure — left warm paper with composed message and human copy, right ink-dark with delivery machinery. Asymmetric 7/5 column split on desktop, stacking to a single column under 768px with the dark technical panel becoming a bordered inset card. Sparse chrome, 96px section padding on desktop, 24px on mobile. Protected app pages keep the split as a persistent left rail (compose/recipients/reports) against a wide working canvas.

Imagery: Diagrams over photography — envelope-to-inbox path drawings, wireframe message wireframes resolving into solid rendered cards, domain-authentication schematics, a half-wireframe/half-solid envelope in CSS and SVG. No stock people, no gradient blobs. The product's own interface is the hero imagery.

7. Signature Design Concept

The public entry is a full-viewport horizontal split (7/5 on desktop): the left half is warm paper #F7F5F0 with an oversized Space Grotesk headline "Send to many. Land in the inbox." set at clamp(56px, 8vw, 104px), flush left, broken across three lines, with a single burnt-orange text link "Start sending" beneath it and an 11px uppercase micro-label "BULK WEBMAIL / INBOX DELIVERY" pinned top-left. The right half is ink #14161A carrying a live delivery panel: a stacked queue of recipient rows in IBM Plex Mono with orange status dots, a large "99.2% inbox placement" numeral, and a wireframe envelope SVG that resolves to solid on hover. A 2px orange rule runs the seam between halves and extends past the top and bottom edges. No centred headline, no subtext paragraph, no blue button, no gradient.

Signature moves: the 50/50 split hero with a 2px orange seam rule running off both top and bottom edges; a wireframe-to-solid hover toggle on the seam or envelope SVG; the dark technical panel as a persistent component reused on Compose and Delivery Reports; oversized flush-left display headline stacked over the light half only; sharp 2px-corner inputs and panels with 1px hairline borders plus a monospace metadata strip ("FROM / DOMAIN / RECIPIENTS / QUEUE") under every form.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: expressive Hero Dimensionality: layered_2d

Landing Hero Motion Brief

• Focal subject: the split seam and the wireframe envelope SVG on the ink-dark delivery panel.
• Input→transformation→outcome thesis: on load, the dark half slides in 12px behind the light half (180–260ms reveal); hovering the seam moves a thin orange line and swaps the envelope diagram from wireframe to solid; delivery numbers count up once on scroll into view.
• Motion vocabulary: restrained reveals, seam-line movement, wireframe-to-solid swap, single count-up. No bounce, no particles.
• Composed first frame: warm paper left half with headline and "Start sending" link; ink right half with queue rows, orange status dots, "99.2% inbox placement" numeral, wireframe envelope; 2px orange seam rule running off top and bottom edges.
• Reduced-motion state: everything static; the seam rule stays put; wireframe remains wireframe; numbers show final values.

9. Non-Functional Requirements

• NFR-1 — Application-owned identity and session continuity (required_inference): Senders must privately own and resume their recipient sets, sends, and delivery reports; sessions must remain bound to the correct sender. Rationale: durable actor-specific state and send records require continuity.
• NFR-2 — Durable persistence (required_inference): Recipient sets, send records, and delivery outcomes must persist in the application database (MariaDB) so they survive across sessions. Rationale: accepted workflows require revisitable state.
• NFR-3 — Protected destinations (required_inference): Compose, Recipients, and Delivery Reports must be inaccessible without an established session; Landing, Sign Up, and Login remain anonymously reachable. Rationale: access contract.
• NFR-4 — Readable text and controls (explicit design constraint): Headlines, wordmarks, labels, numbers, cards' text, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit; no other element covers them. Imagery and decoration may bleed or overlap as the direction asks, but never cover readable text or controls.
• NFR-5 — Reduced motion (explicit design constraint): Under prefers-reduced-motion, provide a usable static arrangement; the seam rule stays put and all motion is disabled.
• NFR-6 — Contrast (explicit design constraint): Ink on paper ≈ 15:1; orange on ink ≈ 5.1:1 at large sizes, reserved for labels ≥16px semibold; body copy never orange on paper.

10. Tech Stack

• Frontend: React application UI.
• Backend: Shared FastAPI process for application APIs and domain modules (bulk send dispatch, recipient-set management, delivery-outcome reporting, identity).
• Database: MariaDB for application-owned persistent data (sender accounts, recipient sets, send records, delivery outcomes).
• Infrastructure: Docker/docker-compose provisioning the backend, database, and frontend services.

11. Assumptions and Constraints

• A-1 (required_inference): Identity is application-owned and self-service; no invitation or provisioning flow is in scope.
• A-2 (required_inference): Every authenticated sender works with their own recipient sets, sends, and reports; no differentiated permissions or role-based visibility exist.
• A-3 (required_inference): Recipients are external actors who receive messages in their own mailboxes; they do not use the product interface.
• A-4 (explicit): The product's promise is inbox placement rather than spam or bulk folders; delivery outcomes are surfaced to the sender through Delivery Reports.
• A-5 (explicit design constraint): The generic indigo/blue-on-white SaaS template is forbidden; the palette, fonts, split-screen layout, and motion direction above are binding.
• A-6 (required_inference): A recipient set must exist before a bulk send can be dispatched; a send must be dispatched before its outcomes can be reviewed.

12. Glossary

• Bulk send: One message dispatched to many recipients in a single operation.
• Recipient set: A named, persisted collection of recipient addresses used in bulk sends.
• Inbox placement: Whether a delivered message arrives in the recipient's inbox rather than spam or bulk folders.
• Delivery Reports: The protected surface where senders review send outcomes and inbox placement.
• Sender: An authenticated human who composes and dispatches bulk sends.
• Recipient: An external human who receives bulk-sent messages in their own inbox.
• Seam: The 2px orange vertical rule dividing the warm paper half from the ink-dark delivery panel.
• Wireframe-to-solid toggle: The hover interaction that swaps dashed outlines for rendered fills on the envelope SVG or seam.