--- id: EMAIL-WP-0003 type: workplan title: "Expected Recipient Reporting and Mailbox Tutorial" domain: custodian repo: email-connect status: active owner: codex topic_slug: custodian created: "2026-06-02" updated: "2026-06-02" state_hub_workstream_id: "438149d2-4f20-42b1-91fd-cdeff29dec7d" --- # EMAIL-WP-0003 - Expected Recipient Reporting and Mailbox Tutorial ## 1. Purpose This workplan extends the mailbox evidence scanner so operators can provide an optional set of target email addresses that were expected to receive notifications. When expected recipients are provided, the scanner should include them in the evidence report even when no mailbox evidence is known for a given recipient. The result is a report that can answer both: ```text What evidence did the mailbox contain? Which expected recipients have no known email-channel evidence? ``` The scanner must continue to work without a target-recipient list. Email events remain evidence, not proof of delivery, awareness, or coordination success. ## 2. User Story As an operator, I want to provide a line-separated list or CSV file of email addresses that were supposed to receive notifications, scan a mailbox for return evidence within a chosen time range, and generate a report where expected recipients are easy to filter and appear before incidental mailbox-only addresses. ## 3. In Scope The workplan shall support: - Optional expected-recipient input from a newline-separated text file. - Optional expected-recipient input from CSV. - CLI and config support for recipient list paths. - Email address normalization and deduplication. - Reports that can be generated without any expected-recipient input. - Reports that include expected recipients with no known evidence. - An explicit `known_recipient` boolean column in the report. - Default report ordering with known recipients first. - An `undef` evidence/report row for expected recipients where nothing is known. - Mail inspection limited to a datetime range. - Excluding all email evidence from messages outside the configured range. - Tests that prove no overclaiming occurs for unknown expected recipients. - A tutorial for generating a mailbox report from configuration through output review. ## 4. Out of Scope The workplan does not require: - Outbound sending. - Proving that all provided expected recipients were actually contacted. - Requiring expected recipients for report generation. - Legal delivery assessment. - A suppression-management UI. - Multi-mailbox correlation. - Cross-batch campaign management. ## 5. Report Semantics Expected recipients are advisory context supplied by the operator. If an expected recipient has no evidence rows, the scanner should emit a conservative unknown row: ```text event_type: diagnostic.expected_recipient.no_evidence assessment_category: undef assessment_subclass: undef.no_signal evidence_strength: none known_recipient: true ``` This row means only: ```text The recipient was supplied as an expected notification target, and this scan found no mailbox evidence for that address in the inspected time range. ``` It must not mean: ```text delivery failed delivery succeeded recipient was not notified recipient ignored the message ``` Mailbox-only evidence rows for addresses not in the supplied expected-recipient set should remain visible with: ```text known_recipient: false ``` If no expected-recipient input is provided, the report should still be generated from mailbox evidence only and `known_recipient` should default to `false`. ## 6. Time Range Semantics The scanner should support an optional inclusive datetime range: ```text --from 2026-06-01T00:00:00Z --to 2026-06-02T23:59:59Z ``` Messages outside the range must be excluded before parsing and evidence generation whenever the message timestamp is available. The range should also be usable from config. If a message has no parseable timestamp, the implementation should either include it with a diagnostic note or exclude it only when the behavior is explicitly documented and tested. Existing `--since` behavior may be retained as a compatibility alias for the lower bound, but the new range should be expressed clearly in documentation. ## 7. CLI Target Example commands: ```text email-connect scan-mailbox --config config/mailbox.yml --out reports/ email-connect scan-mailbox --config config/mailbox.yml --expected-recipients recipients.txt --out reports/ email-connect scan-mailbox --config config/mailbox.yml --expected-recipients recipients.csv --expected-recipient-column email --out reports/ email-connect scan-mailbox --config config/mailbox.yml --from 2026-06-01T00:00:00Z --to 2026-06-02T23:59:59Z --out reports/ ``` ## 8. Work Packages ## T01 - Expected Recipient Input Model ```task id: EMAIL-WP-0003-T01 status: todo priority: high state_hub_task_id: "d1cd0de0-cbd5-4e8d-8179-000ba10e5506" ``` Tasks: ```text Add expected-recipient config fields Add CLI option for expected-recipient file path Support newline-separated email address files Support CSV files with configurable email column Normalize addresses case-insensitively Deduplicate recipient addresses Reject or warn on invalid addresses without aborting the scan ``` Acceptance: ```text The scanner can load zero, one, or many expected recipients from text or CSV. Invalid recipient rows are visible as warnings or diagnostics. ``` ## T02 - Known Recipient Report Column and Ordering ```task id: EMAIL-WP-0003-T02 status: todo priority: high state_hub_task_id: "3d7d3bb8-4118-4158-b874-b4e0527eaa85" ``` Tasks: ```text Add known_recipient boolean column to CSV reports Mark evidence rows true when affected_email_address matches expected recipients Mark mailbox-only rows false when no expected list is provided or no match exists Sort report rows with known recipients first by default Preserve deterministic secondary sorting Document filtering behavior for spreadsheet users ``` Acceptance: ```text Generated reports include known_recipient and place known-recipient rows before unknown-recipient rows by default. ``` ## T03 - No-Evidence Rows for Expected Recipients ```task id: EMAIL-WP-0003-T03 status: todo priority: high state_hub_task_id: "aa737837-2f19-4fbf-9920-f98413bd9779" ``` Tasks: ```text Detect expected recipients with no matching evidence in the inspected range Generate diagnostic.expected_recipient.no_evidence rows for those recipients Use assessment_category undef Use assessment_subclass undef.no_signal Use evidence_strength none Avoid endpoint-quality updates from no-evidence rows Avoid implying delivery failure or delivery success Deduplicate generated no-evidence rows across rescans ``` Acceptance: ```text Expected recipients with no mailbox evidence appear in the report as undef no-signal diagnostics, not as failures or successes. ``` ## T04 - Optional Recipient Context ```task id: EMAIL-WP-0003-T04 status: todo priority: medium state_hub_task_id: "731cf592-1bbe-4143-b21b-721af281528c" ``` Tasks: ```text Keep report generation working when no recipient list is provided Keep report generation working when recipient list is empty Ensure expected-recipient input is not required for mailbox-only reports Ensure mailbox-only evidence remains visible even when expected recipients are provided ``` Acceptance: ```text Reports can be generated with no expected recipients, empty expected recipients, or partial expected recipients. ``` ## T05 - Datetime Range Filtering ```task id: EMAIL-WP-0003-T05 status: todo priority: high state_hub_task_id: "22585e83-d995-42d9-9ab2-c383b055fbb8" ``` Tasks: ```text Add config fields for scan datetime lower and upper bounds Add CLI options for datetime lower and upper bounds Treat --since as a compatibility alias for the lower bound Exclude messages outside the configured range from parsing and evidence generation Define behavior for messages with no parseable Date header Apply filtering consistently to fixture and IMAP scans Store the range on MailboxScan Add tests for inclusive lower and upper bounds ``` Acceptance: ```text When a datetime range is configured, the scanner inspects only messages whose message timestamp falls within the range according to the documented rules. ``` ## T06 - Report and Evidence Tests ```task id: EMAIL-WP-0003-T06 status: todo priority: high state_hub_task_id: "f30cd5b9-5035-42b4-9eca-a104e2b26ecb" ``` Tasks: ```text Add text recipient-list fixture Add CSV recipient-list fixture Add tests for known_recipient true and false rows Add tests for known-recipient-first ordering Add tests for no-evidence undef rows Add tests that no-evidence rows do not update endpoint quality Add tests for report generation with no recipient input Add tests for datetime range exclusion ``` Acceptance: ```text Automated tests prove expected-recipient reporting, optional recipient input, and datetime range filtering. ``` ## T07 - Mailbox Report Tutorial ```task id: EMAIL-WP-0003-T07 status: todo priority: medium state_hub_task_id: "00a29cb9-ac5a-4784-a9c4-7f2d4905405c" ``` Tasks: ```text Create a tutorial for configuring mailbox access Show fixture-based dry run Show live IMAP configuration Show expected-recipient text list usage Show expected-recipient CSV usage Show datetime range usage Explain known_recipient filtering Explain undef no-signal rows Explain evidence limitations and overclaim prevention Include troubleshooting notes for credentials and empty reports ``` Acceptance: ```text A new user can follow the tutorial to generate and interpret an email-connect mailbox evidence report. ``` ## 9. Completion Criteria This workplan is complete when: 1. Expected-recipient input is optional and supports text and CSV files. 2. Reports include `known_recipient`. 3. Known recipients sort first by default. 4. Expected recipients with no evidence produce `undef.no_signal` diagnostic rows. 5. The scanner still works without any expected recipients. 6. Datetime range filtering excludes messages outside the inspected range. 7. Tests cover recipient input, report ordering, no-evidence rows, optional input, and datetime range filtering. 8. A tutorial documents how to generate a mailbox evidence report.