email-connect/workplans/EMAIL-WP-0003-expected-recipient-reporting-and-mailbox-tutorial.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
EMAIL-WP-0003	workplan	Expected Recipient Reporting and Mailbox Tutorial	custodian	email-connect	finished	codex	custodian	2026-06-02	2026-06-02	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:

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:

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:

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:

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:

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:

--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 while a range is active, it is excluded because the scanner cannot confirm that it originated inside the requested window.

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:

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

id: EMAIL-WP-0003-T01
status: done
priority: high
state_hub_task_id: "d1cd0de0-cbd5-4e8d-8179-000ba10e5506"

Tasks:

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:

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

id: EMAIL-WP-0003-T02
status: done
priority: high
state_hub_task_id: "3d7d3bb8-4118-4158-b874-b4e0527eaa85"

Tasks:

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:

Generated reports include known_recipient and place known-recipient rows before
unknown-recipient rows by default.

T03 - No-Evidence Rows for Expected Recipients

id: EMAIL-WP-0003-T03
status: done
priority: high
state_hub_task_id: "aa737837-2f19-4fbf-9920-f98413bd9779"

Tasks:

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:

Expected recipients with no mailbox evidence appear in the report as undef
no-signal diagnostics, not as failures or successes.

T04 - Optional Recipient Context

id: EMAIL-WP-0003-T04
status: done
priority: medium
state_hub_task_id: "731cf592-1bbe-4143-b21b-721af281528c"

Tasks:

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:

Reports can be generated with no expected recipients, empty expected recipients,
or partial expected recipients.

T05 - Datetime Range Filtering

id: EMAIL-WP-0003-T05
status: done
priority: high
state_hub_task_id: "22585e83-d995-42d9-9ab2-c383b055fbb8"

Tasks:

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:

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

id: EMAIL-WP-0003-T06
status: done
priority: high
state_hub_task_id: "f30cd5b9-5035-42b4-9eca-a104e2b26ecb"

Tasks:

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:

Automated tests prove expected-recipient reporting, optional recipient input,
and datetime range filtering.

T07 - Mailbox Report Tutorial

id: EMAIL-WP-0003-T07
status: done
priority: medium
state_hub_task_id: "00a29cb9-ac5a-4784-a9c4-7f2d4905405c"

Tasks:

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:

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.