async_mailer/lib.rs
1//! # async-mailer
2//! A set of async generic `Mailer` and dynamic `dyn DynMailer` traits with runtime-pluggable Outlook (Office365) and SMTP implementations.
3//!
4//! [](https://crates.io/crates/async-mailer)
5//! [][docs]
6//! [](https://deps.rs/repo/github/LeoniePhiline/async-mailer)
7//!
8//! ## Installation
9//!
10//! Add to your `Cargo.toml`:
11//!
12//! ```toml
13//! async-mailer = "0.5.0"
14//! ```
15//!
16//! You can control the re-exported mailer implementations,
17//! as well as [`tracing`](https://docs.rs/crate/tracing) support,
18//! via [crate feature toggles](https://docs.rs/crate/async-mailer/latest/features).
19//!
20//! By default, features `smtp`, `outlook` and `tracing` are enabled.
21//! Use `default-features = false` and `features = [...]` to select features individually.
22//!
23//! # Examples
24//!
25//! Use `new` for a statically typed mailer instance,
26//! or `new_box` / `new_arc` for a type-erased dynamic mailer.
27//!
28//! Microsoft Outlook and SMTP mailer variants are available.
29//!
30//! ## Using the statically typed `Mailer`:
31//!
32//! ```no_run
33//! # async fn test() -> Result<(), Box<dyn std::error::Error>> {
34//! // Both `OutlookMailer` and `SmtpMailer` implement `Mailer`
35//! // and can be used with `impl Mailer` or `<M: Mailer>` bounds.
36//!
37//! use async_mailer::{IntoMessage, Mailer, OutlookMailer, SmtpMailer};
38//!
39//! let mailer: OutlookMailer = OutlookMailer::new(
40//! "<Microsoft Identity service tenant>".into(),
41//! "<OAuth2 app GUID>".into(),
42//! async_mailer::SecretString::from("<OAuth2 app secret>")
43//! ).await?;
44//!
45//! // Alternative:
46//!
47//! let mailer: SmtpMailer = SmtpMailer::new(
48//! "smtp.example.com".into(),
49//! 465,
50//! async_mailer::SmtpInvalidCertsPolicy::Deny,
51//! "<username>".into(),
52//! async_mailer::SecretString::from("<password>")
53//! );
54//!
55//! // Further alternative mailers can be implemented by third parties.
56//!
57//! // Build a message using the re-exported `mail_builder::MessageBuilder'.
58//! //
59//! // For blazingly fast rendering of beautiful HTML mail,
60//! // I recommend combining `askama` with `mrml`.
61//!
62//! let message = async_mailer::MessageBuilder::new()
63//! .from(("From Name", "from@example.com"))
64//! .to("to@example.com")
65//! .subject("Subject")
66//! .text_body("Mail body")
67//! .into_message()?;
68//!
69//! // Send the message using the statically typed `Mailer`.
70//!
71//! mailer.send_mail(message).await?;
72//! # Ok(())
73//! # }
74//! ```
75//!
76//! ## Using the dynamically typed `DynMailer`:
77//!
78//! ```no_run
79//! # async fn test() -> Result<(), async_mailer::DynMailerError> {
80//! use async_mailer::{BoxMailer, IntoMessage, OutlookMailer, SmtpMailer};
81//!
82//! // Both `OutlookMailer` and `SmtpMailer` implement `DynMailer` and can be used as trait objects.
83//! // Here they are used as `BoxMailer`, which is an alias to `Box<dyn DynMailer>`.
84//!
85//! let mailer: BoxMailer = OutlookMailer::new_box( // Or `OutlookMailer::new_arc()`.
86//! "<Microsoft Identity service tenant>".into(),
87//! "<OAuth2 app GUID>".into(),
88//! async_mailer::SecretString::from("<OAuth2 app secret>")
89//! ).await?;
90//!
91//! // Alternative:
92//!
93//! let mailer: BoxMailer = SmtpMailer::new_box( // Or `SmtpMailer::new_arc()`.
94//! "smtp.example.com".into(),
95//! 465,
96//! async_mailer::SmtpInvalidCertsPolicy::Deny,
97//! "<username>".into(),
98//! async_mailer::SecretString::from("<password>")
99//! );
100//!
101//! // Further alternative mailers can be implemented by third parties.
102//!
103//! // The trait object is `Send` and `Sync` and may be stored e.g. as part of your server state.
104//!
105//! // Build a message using the re-exported `mail_builder::MessageBuilder'.
106//! //
107//! // For blazingly fast rendering of beautiful HTML mail,
108//! // I recommend combining `askama` with `mrml`.
109//!
110//! let message = async_mailer::MessageBuilder::new()
111//! .from(("From Name", "from@example.com"))
112//! .to("to@example.com")
113//! .subject("Subject")
114//! .text_body("Mail body")
115//! .into_message()?;
116//!
117//! // Send the message using the implementation-agnostic `dyn DynMailer`.
118//!
119//! mailer.send_mail(message).await?;
120//! # Ok(())
121//! # }
122//! ```
123//!
124//! # Feature flags
125//!
126//! - `outlook`: Enable [`OutlookMailer`].
127//! - `smtp`: Enable [`SmtpMailer`].
128//! - `tracing`: Enable debug and error logging using the [`tracing`](https://docs.rs/crate/tracing) crate.
129//! All relevant functions are instrumented.
130//! - `clap`: Implement [`clap::ValueEnum`](https://docs.rs/clap/latest/clap/trait.ValueEnum.html) for [`SmtpInvalidCertsPolicy`].
131//! This allows for easily configured CLI options like `--invalid-certs <allow|deny>`.
132//!
133//! Default: `outlook`, `smtp`, `tracing`.
134//!
135//! ## Roadmap
136//!
137//! - DKIM support is planned to be implemented on the [`SmtpMailer`].
138//! - Access token auto-refresh is planned to be implemented on the [`OutlookMailer`].
139//!
140//! Further mailer implementations are possible.
141//! Please open an issue and ideally provide a pull request to add your alternative mailer implementation!
142//!
143//! [docs]: https://docs.rs/async-mailer
144
145pub use secrecy::SecretString;
146
147pub use async_mailer_core::mail_send;
148pub use async_mailer_core::mail_send::mail_builder;
149
150pub use async_mailer_core::mail_send::mail_builder::MessageBuilder;
151pub use async_mailer_core::mail_send::smtp::message::{IntoMessage, Message};
152
153// == Mailer ==
154pub use async_mailer_core::Mailer;
155
156// == DynMailer ==
157pub use async_mailer_core::{ArcMailer, BoxMailer, DynMailer, DynMailerError};
158
159#[cfg(feature = "outlook")]
160pub use async_mailer_outlook::*;
161
162#[cfg(feature = "smtp")]
163pub use async_mailer_smtp::*;