# email-message
Core email address and outbound message model primitives.
## Scope contract
- This crate models outbound email content and addresses.
- RFC822/MIME wire parsing and rendering are provided by `email-message-wire`.
- Provider-specific limits and operational policies belong to transport crates.
## Stability Contract
- `EmailAddress` values are normalized via `addr-spec` during parsing.
- Address display-name formatting may be canonicalized during render (`Display`) and is not guaranteed byte-for-byte equivalent with source text.
- Address/message parse-render roundtrips preserve semantic values (mailbox/group membership and header meaning), but not raw wire formatting details.
- Public enums marked `#[non_exhaustive]` may gain variants in minor releases.
## Feature Flags
- `serde`: enables `Serialize`/`Deserialize` derives for public model types.
- `schemars`: enables `JsonSchema` derives for public model types.
- `arbitrary`: enables `arbitrary::Arbitrary` derives to support fuzz/property generation.
## std support
This crate currently requires `std`.
### Why no `no_std` today?
- Parsing backends currently depend on `std`.
- The crate uses owned strings/collections and parser components that are not `no_std`-ready.
## MIME model
- Enable the `mime` feature to use `Body::Mime` and `MimePart`.
- MIME parsing/rendering is provided by `email-message-wire`.
## Wire format support
- RFC822/MIME parsing and rendering are provided by `email-message-wire`.
## Metadata policy
- Put provider-agnostic message semantics in `Message`.
Examples: `Date`, `Message-ID`, `Sender`, recipients, body, attachments.
- Put arbitrary outbound headers in `Message.headers` when they should survive both SMTP and structured API paths.
- Put provider-specific controls in transport crates via typed `TransportOptions`, not in the message model.
- Avoid adding fields to `Message` unless they have clear cross-provider meaning and stable semantics across structured and raw delivery.
## Worker-friendly payloads
- With the `serde` feature enabled, `Message` is a good serializable content payload inside a queued worker envelope such as `email_worker::EmailJob`.
- `AttachmentBody::Bytes` is still the direct send/render form.
- `AttachmentBody::Reference(AttachmentReference)` is available for large attachments that should be dereferenced by a worker before transport delivery.
- Reference resolution policy belongs outside this crate so the core model stays transport-agnostic.
## Development
- Run tests: `cargo test -p email-message --all-features`
- Run clippy: `cargo clippy -p email-message --all-targets --all-features -- -D warnings`
- Run benches: `cargo bench -p email-message`