infrastructure-mail-headers

Header field extraction and classification (noreply/system-sender detection) over foundation-mail-message::Email

What it is for

# infrastructure-mail-headers

Header field extraction and classification (noreply/system-sender detection) over foundation_mail_message::Email.

Refactored, not ported, from rust-gmail-manager/src/headers/{service, classify,parser}.rs (Gate 4.5 provenance — see CHANGELOG.md). The source's parser.rs::parse_from_gmail_headers walked a raw Vec<(String, String)> of Gmail API header pairs (From, Message-ID, In-Reply-To, List-Id, List-Unsubscribe, Precedence, Auto-Submitted) pulled straight from infrastructure_adapters_google_gmail::Message's JSON. This crate never touches that shape or IMAP's raw RFC5322 bytes — it reads only foundation_mail_message::Email, the provider-agnostic type both infrastructure-adapters-google-gmail and infrastructure-imap already convert into.

OQ4 finding (sprint 3.45 doc), resolved 2026-08-10

Email (crate 1, crates/foundation/mail-message) used to be deliberately flat — id, thread_id, folders, from, to, cc, bcc, subject, date, parts only, no arbitrary RFC5322 headers. Concretely, neither infrastructure-adapters-google-gmail::email_from_message nor infrastructure-imap's rfc822_to_email copied Message-ID, In-Reply-To, List-Id, List-Unsubscribe, Precedence, or Auto-Submitted into the Email they built, despite both providers' raw sources carrying them. TD-MAIL-EMAIL-NO-RAW-HEADERS (docs/TECH-DEBT.md) tracked this as debt rather than a bug in crate 1 — Gate 4.5's first-consumer rule wanted a second consumer to ratify widening Email before it landed. An independent Gate 4 review of this crate ratified the fix: Email gained six Option<String> fields for those exact headers, and both real converters now populate them from the raw headers they already parse.

Consequence: mm's original classify_mail_type scored five signals (list_unsubscribe, list_id, precedence, auto_submitted, in_reply_to) plus subject keywords plus noreply-sender detection to produce five classes (personal/transactional/promotional/system/unknown). All five signals now survive through Email, and classify restores mm's exact scoring and precedence rules — see classify.rs's module doc comment for the full breakdown. MailClass::Promotional is back.

tests/oq4_provider_evidence.rs runs this crate's real Gmail-shaped and IMAP-shaped Email values (not hand-built stand-ins) through from_address::parse_email_from and classify::classify to prove the full signal set — including the six restored headers — parses and classifies identically across both real providers.

Capabilities

MailClass

Mail class classification (personal / transactional / promotional /

ParsedFrom

From address parsing: display name / local part / domain extraction,

How to use it

No examples/ target and no doctest in this crate's rustdoc. The tests listed under Verification are the closest executable usage.

Module structure

infrastructure_mail_headers

• classify
• from_address

flowchart TD
  n_infrastructure_mail_headers["infrastructure_mail_headers"]
  n_infrastructure_mail_headers --> n_classify["classify"]
  n_infrastructure_mail_headers --> n_from_address["from_address"]

Public surface

`classify`

`from_address`

Re-exports. Exported here, defined elsewhere.

Boundary

Reaches into foundation.

Shares tier infrastructure with 82 other crates: infrastructure-acquire, infrastructure-adapters-google-calendar, infrastructure-adapters-google-gmail, infrastructure-adapters-google-places, infrastructure-adapters-google-trends, infrastructure-adapters-shodan, infrastructure-adapters-yelp, infrastructure-agent, … (82 total).

_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._

Where it sits

Tier flow. Which tiers this crate's own edges cross.

flowchart LR
  n_infrastructure["infrastructure"] --> n_foundation["foundation"]

Dependencies

Runtime, in this workspace.

Development, in this workspace.

Development, from outside the workspace.

Build. None.

Depended on by. Nothing in this workspace.

Signal flow — what reaches this crate, and what it reaches.

flowchart LR
  SELF["infrastructure-mail-headers"]
  SELF -->|development| n_infrastructure_adapters_google_gmail["infrastructure-adapters-google-gmail"]
  SELF -->|runtime| n_foundation_mail_message["foundation-mail-message"]
  classDef self fill:#1f883d,stroke:#1f883d,color:#fff;
  class SELF self;

Feature flags

No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.

Targets

Error model

No public error type was detected: no public item declares a type named *Error, and no public signature returns one.

Operational characteristics

No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.

Configuration

No environment variable is read with a literal name anywhere in this crate. A variable whose key is computed at run time cannot be listed here, and is not claimed to be absent.

Related capabilities

No workspace crate depends on this one.

Verification

Evidence by module. How often each public module is named by something executable.

What the tests establish, by name:

• gmail_and_imap_shaped_email_classify_identically_for_the_same_logical_message — tests/oq4_provider_evidence.rs
• gmail_and_imap_shaped_promotional_newsletter_classify_identically — tests/oq4_provider_evidence.rs
• gmail_shaped_personal_message_classifies_as_personal — tests/oq4_provider_evidence.rs
• imap_shaped_personal_message_classifies_as_personal — tests/oq4_provider_evidence.rs
• human_sender_with_transactional_subject_is_transactional_not_system — src/classify.rs
• in_reply_to_is_a_transactional_signal — src/classify.rs
• list_unsubscribe_alone_is_enough_for_promotional — src/classify.rs
• missing_subject_and_human_sender_is_personal — src/classify.rs
• noreply_with_no_transactional_signal_is_unknown_not_personal — src/classify.rs
• personal_no_markers — src/classify.rs
• promotional_bulk_newsletter_with_list_unsubscribe — src/classify.rs
• promotional_precedence_is_case_insensitive — src/classify.rs
• system_noreply_with_transactional_subject — src/classify.rs
• tied_auto_submitted_and_list_id_signals_land_unknown — src/classify.rs
• transactional_receipt_keyword — src/classify.rs
• unparseable_from_address_is_treated_as_not_noreply — src/classify.rs
• detects_noreply — src/from_address.rs
• extracts_domain_and_root_domain — src/from_address.rs
• extracts_from_angle_brackets — src/from_address.rs
• human_sender_is_not_machine — src/from_address.rs
• invalid_email_returns_none — src/from_address.rs
• lowercases_email — src/from_address.rs
• machine_sender_matches_hyphen_and_plus_suffixes — src/from_address.rs
• parse_email_from_none_on_empty_from — src/from_address.rs
• parse_email_from_reads_the_from_field — src/from_address.rs
• preserves_plus_alias — src/from_address.rs
• quoted_sender — src/from_address.rs
• trims_whitespace — src/from_address.rs

Documentation coverage

pie showData
    title Public items with rustdoc
    "Documented" : 5
    "No rustdoc detected" : 0

Metrics

pie showData
    title Public API by kind
    "enum" : 1
    "function" : 3
    "struct" : 1

pie showData
    title Rust source composition
    "Code" : 335
    "Blank or comment" : 217

Generation

Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.