email_message/
lib.rs

1//! Typed email addresses, message content, and validated outbound messages.
2//!
3//! Use this crate to construct provider-independent email values. RFC 822/MIME
4//! byte parsing and rendering are intentionally handled by
5//! `email-message-wire`, while transport crates apply provider-specific limits
6//! and delivery policies.
7//!
8//! # Quick start
9//!
10//! ```rust
11//! use email_message::{Address, Body, Message};
12//!
13//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
14//! let message = Message::builder(Body::text("Hello"))
15//!     .from_mailbox("sender@example.com".parse()?)
16//!     .to(vec![Address::Mailbox("recipient@example.com".parse()?)])
17//!     .subject("Welcome")
18//!     .build_outbound()?;
19//!
20//! assert_eq!(message.as_message().subject(), Some("Welcome"));
21//! # Ok(())
22//! # }
23//! ```
24//!
25//! # Cargo features
26//!
27//! No features are enabled by default.
28//!
29//! - `mime` exposes [`MimePart`], the low-level MIME tree. The other MIME value
30//!   types are always available. The `email-message-wire` crate enables this
31//!   feature on its dependency because rendering needs the tree.
32//! - `serde` implements serialization and deserialization for public model
33//!   types. Binary attachment and MIME bodies use padded base64 strings.
34//! - `schemars` implements JSON Schema generation. When combined with `mime`,
35//!   schemas include [`MimePart`].
36//! - `arbitrary` implements `arbitrary::Arbitrary` for generated test data,
37//!   including feature-gated model types that are also enabled.
38//! - `rfc5322-string-compat` lets `serde` deserializers and `schemars` schemas
39//!   accept RFC 5322 address strings in addition to the typed object shape. It
40//!   has no effect unless `serde` or `schemars` is also enabled.
41//!
42//! All features are additive and may be enabled together.
43//!
44//! # Platform support
45//!
46//! This is a `std` crate with no operating-system APIs or target-specific
47//! implementation. It supports Rust targets that provide the standard library.
48
49/// RFC 5322 mailboxes, groups, addresses, and address lists.
50pub mod address;
51/// Validated RFC 5322 `addr-spec` email addresses.
52pub mod email;
53/// Message bodies, attachments, headers, builders, and outbound validation.
54pub mod message;
55/// Validated RFC 5322 `Message-ID` values.
56pub mod message_id;
57pub mod mime_types;
58
59pub use address::{
60    Address, AddressBackendError, AddressList, AddressParseError, Group, GroupParseError,
61    MAX_ADDRESS_INPUT_BYTES, Mailbox, MailboxList, MailboxParseError,
62};
63pub use email::{EmailAddress, EmailAddressParseError};
64pub use message::{
65    Attachment, AttachmentBody, AttachmentReference, Body, Disposition, Envelope, Header,
66    HeaderValidationError, Message, MessageBuilder, MessageValidationError, OutboundMessage,
67};
68pub use message_id::{MessageId, MessageIdParseError};
69
70pub use mime_types::{
71    ContentDisposition, ContentDispositionParseError, ContentTransferEncoding,
72    ContentTransferEncodingParseError, ContentType, ContentTypeParseError, MediaType,
73    ParameterValue,
74};
75
76#[cfg(feature = "mime")]
77pub use mime_types::MimePart;
78
79#[derive(Debug, thiserror::Error)]
80#[non_exhaustive]
81/// Error returned when parsing one of the crate's core string value types.
82pub enum ParseError {
83    /// An email address failed validation.
84    #[error(transparent)]
85    EmailAddress(#[from] EmailAddressParseError),
86    /// A mailbox failed to parse.
87    #[error(transparent)]
88    Mailbox(#[from] MailboxParseError),
89    /// An address group failed to parse.
90    #[error(transparent)]
91    Group(#[from] GroupParseError),
92    /// A mailbox-or-group address failed to parse.
93    #[error(transparent)]
94    Address(#[from] AddressParseError),
95}
email_message/lib.rs

email_message/
lib.rs
