Expand description
§pata — Evidence for every address
Pata is a fast, lightweight email validation library for Rust. It checks syntax, domain routing, and mailbox responses without presenting uncertain results as facts.
Pata supports Rust 1.94.1 and later.
The name comes from the Hindi and Urdu word pata (पता, پتہ): an
address, location, clue, or knowledge.
§Local validation
Local validation performs no network I/O:
use pata::{Validator, Verdict};
let validator = Validator::local();
let report = validator.validate("maya@example.com").await;
assert_eq!(report.verdict(), Verdict::Plausible);
assert_eq!(report.address().unwrap().domain().ascii(), "example.com");Malformed input is a validation result rather than an operational error:
use pata::{Validator, Verdict};
let report = Validator::local().validate("not an address").await;
assert_eq!(report.verdict(), Verdict::Invalid);
assert!(report.address().is_none());Pata deliberately does not call a passively inspected address “verified” or
claim that it exists. A successful report is Plausible; proof of control
belongs to a separate confirmation workflow.
§Domain and mailbox checks
Network validation is opt-in. Enable runtime-portable for domain checks or
runtime-portable-tls for domain and mailbox checks.
Network::system reads the operating system’s
resolver configuration and uses portable async-io sockets and Futures I/O
internally. The TLS feature adds authenticated Rustls STARTTLS. Neither feature
requires the application to run Tokio or Smol. The first call starts one shared
DNS worker thread that remains for the process lifetime.
use pata::{Network, Mode, Validator};
async fn inspect_domain() -> pata::Result<()> {
let validator = Validator::builder()
.mode(Mode::Domain)
.network(Network::system()?)
.build()?;
let report = validator.validate("maya@example.com").await;
println!("{:?}: {:?}", report.verdict(), report.domain_status());
Ok(())
}Mailbox observation additionally requires a multi-label DNS identity for the
probing host. Pata opens a bounded SMTP conversation, attempts authenticated
STARTTLS when advertised, uses the null reverse path, submits one RCPT TO,
resets the transaction, and quits. It never issues DATA and never sends
message content.
use pata::{Network, Mode, Validator};
async fn inspect_mailbox() -> pata::Result<()> {
let validator = Validator::builder()
.mode(Mode::Mailbox)
.network(Network::system()?)
.probe_identity("validator.example.com")?
.build()?;
let report = validator.validate("maya@example.com").await;
println!("{:?}", report.mailbox_status());
Ok(())
}Domain reveals only the DNS domain to configured resolvers. Mailbox
reveals the full address to a receiving mail server. Call
Validator::plan before execution when an
application needs to display or enforce that disclosure boundary.
§Runtime model
The default adapter works when polled by any Futures-compatible executor.
Advanced applications can supply an owned dns::Resolver
and runtime::Connector,
runtime::Timer, and optional authenticated
runtime::TlsConnector. No Hickory, Rustls,
Tokio, or Smol type appears in Pata’s validation and report APIs.
runtime-portable supplies the built-in system DNS, TCP, and timer adapter.
runtime-portable-tls adds its authenticated Rustls STARTTLS upgrader.
Drop a validation future to cancel that caller’s operation. Pata returns no partial report after cancellation and never caches recipient outcomes. A shared DNS lookup can still serve another concurrent caller.
The opt-in serde feature serializes the complete report, including the
original address. Debug output remains redacted. Applications must treat
serialized reports as sensitive data and apply their own retention controls.
§Classification and policy
The default classification feature provides versioned, checked-in data for
role mailboxes, common free-mail services, reviewed disposable services, and a
small conservative set of provider-domain typo suggestions. Reports retain the
compiled data revision and never silently rewrite an address. Runtime FSTs live
beside their Rust consumer. The snapshot manifest lives with its repository
generator in
examples/classifier_snapshot/.
The crate root contains the third-party notice and license texts.
The classifier_snapshot example verifies checked-in artifacts and rebuilds a
named FST only when the supplied source matches its pinned checksum.
Application rules remain explicit policy inputs. Exact IDNA-normalized domain
allow and deny rules are configured through Policy::builder;
deny rules make Policy::accepts return false without
inventing DNS or SMTP failures.
The registration policy accepts reports with retained risk warnings. The strict policy rejects those reports. The transactional policy also requires an explicit or implicit mail route. Domain allow rules change policy evaluation without removing the underlying classifier findings.
§Batch and operational capabilities
Validator::validate_all accepts a stream,
applies bounded concurrency, coalesces successful domain lookups, and preserves
input order. Shared cache keys contain domains only; recipient outcomes and
complete addresses are never cached.
Optional features keep operational concerns additive:
diagnosticsaudits DNS route safety and configured SMTP/TLS capabilities without accepting or disclosing a recipient;proxyprovides a bounded runtime-neutral SOCKS5 connector with redacted RFC 1929 credentials and local DNS destination revalidation;postureinspects SPF, DMARC, MTA-STS, and TLS-RPT publication separately from address deliverability;tracingemits completion metadata without the address or domain; andserdeexplicitly serializes complete sensitive reports.
The default feature set contains only classification. It performs no network
I/O and keeps DNS, SMTP, TLS, proxy, provider, and confirmation dependencies
opt-in. --no-default-features retains parsing, local findings, policy,
reports, inspection, and batch validation without classifier data or network
code.
§Interpreting results
Pata reports observations separately from application policy:
Invalidmeans the input grammar failed.Undeliverablerequires a decisive domain or recipient result.Unknownmeans the requested network observation could not conclude.Riskyrecords policy-selected warnings such as disposable service use.Plausiblemeans the requested checks found no decisive failure; it is not proof of ownership or future delivery.
§External lookups and confirmation
These capabilities are separate, opt-in operations. They never run during
Validator::validate, never add findings, and
never change Verdict:
gravatarderives Gravatar’s SHA-256 identifier and provides a bounded, runtime-neutral profile client with optional authentication. A lookup discloses a deterministic address hash to Gravatar. The profile endpoint resolves only a profile’s primary address, and profile presence does not validate the mailbox.breachprovides authenticated HIBP direct and hash-range lookups. Direct lookup sends the complete address and returns public breach details. Hash-range lookup sends only the first six SHA-1 characters and returns breach names. Neither path caches address results. Both distinguish absence from authentication, access, rate limiting, transport, and provider failures. Rate-limited results retain a whole-secondRetry-Afterhint when HIBP supplies one. Applications that display HIBP-derived results must provide the attribution required by HIBP’s Creative Commons license.confirmationgenerates cryptographically random one-time tokens, stores only SHA-256 token identifiers with the challenged address and expiry, compares identifiers in constant time, and requires application-provided asynchronous storage and delivery. The store’s atomic-consume contract provides single use across concurrent callers.
use pata::{Address, gravatar::GravatarId};
let address = Address::parse("maya@example.com")?;
let id = GravatarId::new(&address);
assert_eq!(id.as_str().len(), 64);Provider acceptance of a confirmation message is not proof. Only successful
atomic consumption of the recipient’s token creates a
confirmation::Confirmation, recording
the controlled address and confirmation time.
§Feature flags
- Default:
classification. - Data and validation:
classification,dns,smtp,serde. - Runtime and operations:
runtime-portable,runtime-portable-tls,proxy,diagnostics,posture,tracing. - Explicit external capabilities:
gravatar,breach,confirmation.
--no-default-features retains owned parsing, policy, reports, planning, and
batch validation with no network implementation. Optional provider clients use
Pata’s runtime-neutral Tez transport privately; no Tokio, Smol, Tez, Hickory,
or Rustls type appears in their public contracts.
§Security and privacy
Pata blocks loopback, private, link-local, multicast, documentation, benchmark,
and other non-public SMTP destinations after DNS resolution. It bounds input,
concurrency, DNS routes, protocol responses, connections, commands, and total
execution time. One mailbox observation tries at most 16 destinations and
accepts at most 8 KiB for each SMTP reply. SMTP probes never authenticate,
never issue DATA, and never send message content.
Address debug output, proxy credentials, API keys, confirmation tokens, and
deterministic Gravatar identifiers are redacted. The serde feature
intentionally serializes complete reports, including their original address;
applications own access controls, retention, and deletion.
§What Pata can establish
Syntax, DNS, and SMTP are observations at different strengths. SMTP acceptance may be a catch-all, delayed policy decision, or anti-enumeration response. Gravatar and breach corpus membership are enrichment, not validation. Only a completed confirmation demonstrates control, and even that proof ages independently of future deliverability. Pata preserves those distinctions so applications can apply policy without manufacturing certainty.
Re-exports§
pub use posture::DomainPosture;pub use posture::RecordStatus;
Modules§
- breach
- Explicit account-exposure lookup.
- confirmation
- Runtime-neutral proof-of-control challenges.
- diagnostics
- Redaction-safe network readiness diagnostics.
- dns
- Runtime-neutral DNS mail-routing capabilities.
- gravatar
- Explicit Gravatar profile enrichment.
- posture
- Optional receiving-domain security posture.
- proxy
- Runtime-neutral SOCKS5 support for SMTP connections.
- runtime
- Runtime-neutral SMTP I/O extension points.
Structs§
- Address
- A parsed, owned mailbox address.
- Classification
- Offline classification attached to an address.
- Domain
- An owned email domain with display and DNS forms.
- Finding
- One semantic observation retained in a report.
- Limits
- Resource bounds applied by a validator.
- Network
- Runtime-neutral capabilities used by domain and mailbox validation.
- Parse
Error - An address parsing error that never contains the sensitive input.
- Plan
- A no-I/O description of the work a validator would perform.
- Policy
- Deterministic rules that reduce a report to a verdict.
- Policy
Builder - Builds a custom deterministic validation policy.
- Report
- A complete email address validation result.
- Report
Metadata - Provenance for one validation report.
- Smtp
Policy - Safety and behavior controls for SMTP recipient observation.
- Timeouts
- Time bounds applied to network validation stages.
- Validator
- An immutable, reusable address validator.
- Validator
Builder - Builds a checked validator.
Enums§
- Catch
All - Whether Pata performs a generated-recipient catch-all check.
- Certainty
- How directly an observation supports a finding.
- Domain
Status - The DNS mail-routing conclusion attached to a report.
- Error
- An error that prevents construction of a validator or built-in capability.
- Finding
Code - A stable machine-readable finding identifier.
- Mailbox
Status - The latest bounded SMTP recipient observation.
- Mode
- How far one validation proceeds.
- Outcome
- The result category of one finding.
- Parse
Error Kind - The stable category of an address parsing failure.
- Policy
Kind - The identity of a built-in validation policy.
- TlsPolicy
- STARTTLS behavior for mailbox observation.
- Verdict
- Pata’s policy conclusion for an address.
Type Aliases§
- Result
- A result returned by fallible Pata configuration operations.