domain-sender-reputation

Email sender identity normalization and trust/reputation scoring

What it is for

# domain-sender-reputation

Email sender identity normalization and trust/bulk reputation scoring — used to decide send-safety (is this a sender worth replying to / a bounce-back safe recipient / a machine sender not worth alerting on).

Sprint 3.45 crate 9 (tools-mail-manager harvest). Lifted from rust-gmail-manager/src/sender/{normalize,scoring,model}.rs — see CHANGELOG.md for the full Gate 4.5 provenance and what was deliberately not lifted.

Two independent concerns

• normalize — turn a raw From: header into a normalize::CanonicalSender:

lowercased/trimmed address, display name, domain, root domain, and noreply/machine-sender detection. Pure, no I/O.

• scoring — turn interaction counts (inbox/spam/trash/starred) into a

0-100 trust score (Bayesian-smoothed) and a 0-100 bulk score, and classify the pair into a scoring::ReputationClass. Pure, no I/O.

models::SenderProfile/models::SenderDomain assemble the two into a persistable record; repository::SenderReputationRepository is the trait a consumer implements against its own store (no concrete backend ships here — see that module's doc comment for why).

Composition, not duplication (Gate 0.5)

normalize::CanonicalSender::to_contact builds a domain_contact::Contact by calling Contact::email rather than inventing a parallel address type — this crate owns parsing raw sender headers into a canonical, scoreable identity, and hands off to domain-contact's existing shape once that identity is linked to a known party.

Example

use domain_sender_reputation::{
models::{InteractionCounts, SenderProfile},
scoring::SenderConfig,
};
use uuid::Uuid;

let config = SenderConfig::default();
let profile = SenderProfile::from_raw_sender(
Uuid::new_v4(),
"Newsletter <news@example.com>",
InteractionCounts {
message_count: 40,
inbox_count: 40,
spam_count: 0,
trash_count: 0,
starred_count: 0,
},
None,
None,
&config,
)
.expect("valid sender header");

assert!(profile.is_machine_sender);

Capabilities

SenderReputationError

Sender-reputation errors.

InteractionCounts

Sender and sender-domain reputation records.

SenderDomain

Sender and sender-domain reputation records.

SenderProfile

Sender and sender-domain reputation records.

CanonicalSender

Sender identity normalization: canonicalize a raw From:-style header

SenderReputationRepository

Sender-reputation persistence trait.

SenderReputationResult

Sender-reputation persistence trait.

SenderSort

Sender-reputation persistence trait.

scoring (other)

Trust/bulk reputation scoring: Bayesian-smoothed trust score, a

ReputationClass

Trust/bulk reputation scoring: Bayesian-smoothed trust score, a

SenderConfig

Trust/bulk reputation scoring: Bayesian-smoothed trust score, a

How to use it

From this crate's own rustdoc:

use domain_sender_reputation::{
    models::{InteractionCounts, SenderProfile},
    scoring::SenderConfig,
};
use uuid::Uuid;

let config = SenderConfig::default();
let profile = SenderProfile::from_raw_sender(
    Uuid::new_v4(),
    "Newsletter <news@example.com>",
    InteractionCounts {
        message_count: 40,
        inbox_count: 40,
        spam_count: 0,
        trash_count: 0,
        starred_count: 0,
    },
    None,
    None,
    &config,
)
.expect("valid sender header");

assert!(profile.is_machine_sender);

Module structure

domain_sender_reputation

• errors
• models
• normalize
• repository
• scoring

flowchart TD
  n_domain_sender_reputation["domain_sender_reputation"]
  n_domain_sender_reputation --> n_errors["errors"]
  n_domain_sender_reputation --> n_models["models"]
  n_domain_sender_reputation --> n_normalize["normalize"]
  n_domain_sender_reputation --> n_repository["repository"]
  n_domain_sender_reputation --> n_scoring["scoring"]

Public surface

`errors`

`models`

`normalize`

`repository`

`scoring`

Re-exports. Exported here, defined elsewhere.

Boundary

Reaches into foundation.

Shares tier domain with 41 other crates: domain-agreements, domain-ai-report, domain-billing, domain-catalog, domain-classify, domain-comments, domain-competitive-intel, domain-contact, … (41 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_domain["domain"] --> n_foundation["foundation"]

Dependencies

Runtime, in this workspace.

Runtime, from outside the 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["domain-sender-reputation"]
  SELF -->|runtime| n_domain_contact["domain-contact"]
  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

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:

• test_domain_aggregate_ignores_sender_level_machine_flags — src/models.rs
• test_from_raw_sender_noreply_is_bulk_leaning — src/models.rs
• test_from_raw_sender_rejects_unparseable_header — src/models.rs
• test_from_raw_sender_scores_and_classifies — src/models.rs
• test_canonicalize_lowercases_email — src/normalize.rs
• test_canonicalize_preserves_plus_alias — src/normalize.rs
• test_canonicalize_trims_whitespace — src/normalize.rs
• test_extract_domain — src/normalize.rs
• test_extract_from_angle_brackets — src/normalize.rs
• test_human_sender_not_machine — src/normalize.rs
• test_invalid_email_returns_none — src/normalize.rs
• test_noreply_detected — src/normalize.rs
• test_quoted_sender — src/normalize.rs
• test_to_contact_uses_canonical_email_as_value — src/normalize.rs
• test_count_senders_scoped_by_tenant — src/repository.rs
• test_get_sender_missing_returns_none — src/repository.rs
• test_upsert_then_get_round_trips — src/repository.rs
• test_bulk_score_bounded — src/scoring.rs
• test_classify_bulk — src/scoring.rs
• test_classify_mixed — src/scoring.rs
• test_classify_trusted — src/scoring.rs
• test_human_low_volume_low_bulk — src/scoring.rs
• test_noreply_high_bulk — src/scoring.rs
• test_reputation_class_as_str_matches_mm — src/scoring.rs
• test_spammy_sender_low_trust — src/scoring.rs
• test_trust_score_bounded — src/scoring.rs
• test_trusted_sender_high_trust — src/scoring.rs

Documentation coverage

pie showData
    title Public items with rustdoc
    "Documented" : 19
    "No rustdoc detected" : 2

Metrics

pie showData
    title Public API by kind
    "enum" : 3
    "function" : 4
    "method" : 7
    "struct" : 5
    "trait" : 1
    "type alias" : 1

pie showData
    title Rust source composition
    "Code" : 725
    "Blank or comment" : 342

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.