Crate async_mailer

Expand description

§async-mailer

A set of async generic Mailer and dynamic dyn DynMailer traits with runtime-pluggable Outlook (Office365) and SMTP implementations.

§Installation

Add to your Cargo.toml:

async-mailer = "0.5.0"

You can control the re-exported mailer implementations, as well as tracing support, via crate feature toggles.

By default, features smtp, outlook and tracing are enabled. Use default-features = false and features = [...] to select features individually.

§Examples

Use new for a statically typed mailer instance, or new_box / new_arc for a type-erased dynamic mailer.

Microsoft Outlook and SMTP mailer variants are available.

§Using the statically typed `Mailer`:

// Both `OutlookMailer` and `SmtpMailer` implement `Mailer`
// and can be used with `impl Mailer` or `<M: Mailer>` bounds.

use async_mailer::{IntoMessage, Mailer, OutlookMailer, SmtpMailer};

let mailer: OutlookMailer = OutlookMailer::new(
    "<Microsoft Identity service tenant>".into(),
    "<OAuth2 app GUID>".into(),
    async_mailer::SecretString::from("<OAuth2 app secret>")
).await?;

// Alternative:

let mailer: SmtpMailer = SmtpMailer::new(
    "smtp.example.com".into(),
    465,
    async_mailer::SmtpInvalidCertsPolicy::Deny,
    "<username>".into(),
    async_mailer::SecretString::from("<password>")
);

// Further alternative mailers can be implemented by third parties.

// Build a message using the re-exported `mail_builder::MessageBuilder'.
//
// For blazingly fast rendering of beautiful HTML mail,
// I recommend combining `askama` with `mrml`.

let message = async_mailer::MessageBuilder::new()
    .from(("From Name", "from@example.com"))
    .to("to@example.com")
    .subject("Subject")
    .text_body("Mail body")
    .into_message()?;

// Send the message using the statically typed `Mailer`.

mailer.send_mail(message).await?;

§Using the dynamically typed `DynMailer`:

use async_mailer::{BoxMailer, IntoMessage, OutlookMailer, SmtpMailer};

// Both `OutlookMailer` and `SmtpMailer` implement `DynMailer` and can be used as trait objects.
// Here they are used as `BoxMailer`, which is an alias to `Box<dyn DynMailer>`.

let mailer: BoxMailer = OutlookMailer::new_box( // Or `OutlookMailer::new_arc()`.
    "<Microsoft Identity service tenant>".into(),
    "<OAuth2 app GUID>".into(),
    async_mailer::SecretString::from("<OAuth2 app secret>")
).await?;

// Alternative:

let mailer: BoxMailer = SmtpMailer::new_box( // Or `SmtpMailer::new_arc()`.
    "smtp.example.com".into(),
    465,
    async_mailer::SmtpInvalidCertsPolicy::Deny,
    "<username>".into(),
    async_mailer::SecretString::from("<password>")
);

// Further alternative mailers can be implemented by third parties.

// The trait object is `Send` and `Sync` and may be stored e.g. as part of your server state.

// Build a message using the re-exported `mail_builder::MessageBuilder'.
//
// For blazingly fast rendering of beautiful HTML mail,
// I recommend combining `askama` with `mrml`.

let message = async_mailer::MessageBuilder::new()
    .from(("From Name", "from@example.com"))
    .to("to@example.com")
    .subject("Subject")
    .text_body("Mail body")
    .into_message()?;

// Send the message using the implementation-agnostic `dyn DynMailer`.

mailer.send_mail(message).await?;

§Feature flags

outlook: Enable OutlookMailer.
smtp: Enable SmtpMailer.
tracing: Enable debug and error logging using the tracing crate. All relevant functions are instrumented.
clap: Implement clap::ValueEnum for SmtpInvalidCertsPolicy. This allows for easily configured CLI options like --invalid-certs <allow|deny>.

Default: outlook, smtp, tracing.

§Roadmap

DKIM support is planned to be implemented on the SmtpMailer.
Access token auto-refresh is planned to be implemented on the OutlookMailer.

Further mailer implementations are possible. Please open an issue and ideally provide a pull request to add your alternative mailer implementation!

Re-exports§

pub use async_mailer_core::mail_send;
pub use async_mailer_core::mail_send::mail_builder;

Structs§

Message
MessageBuilder: Builds an RFC5322 compliant MIME email message.
OutlookMailer: An Outlook mailer client, implementing the async_mailer_core::Mailer and async_mailer_core::DynMailer traits to be used as generic mailer or runtime-pluggable trait object.
SmtpMailer: An SMTP mailer client, implementing the async_mailer_core::Mailer and async_mailer_core::DynMailer traits to be used as generic mailer or runtime-pluggable trait object.

Enums§

OutlookAccessTokenError: Error returned by OutlookMailer::new if an access token cannot be retrieved.
OutlookMailerError: Error returned by OutlookMailer::new and OutlookMailer::send_mail.
SmtpInvalidCertsPolicy: Pass to SmtpMailer::new to either allow or deny invalid SMTP certificates.
SmtpMailerError: Error returned by SmtpMailer::new and SmtpMailer::send_mail.

Traits§

DynMailer: Object-safe DynMailer trait, usable as &DynMailer, ArcMailer (Arc<dyn DynMailer>) or BoxMailer (Box<dyn DynMailer>).
IntoMessage
Mailer: Statically typed Mailer, to be used in impl Mailer or <M: Mailer> bounds.

Type Aliases§

ArcMailer: Arc-wrapped dyn DynMailer
BoxMailer: Boxed dyn DynMailer
DynMailerError: Type-erased mailer error, for use of DynMailer as trait object.
SecretString: Secret string type.

Crate async_mailerCopy item path