README.md

async-mailer

A set of async generic Mailer and dynamic dyn DynMailer traits with runtime-pluggable Microsoft 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 (Office365) and SMTP 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", "[email protected]"))
    .to("[email protected]")
    .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 dyn DynMailer / BoxMailer / ArcMailer:

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", "[email protected]"))
    .to("[email protected]")
    .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.
• 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!