Crate async_mailer

source ·
Expand description

async-mailer

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

Crates.io Documentation Dependency status

Installation

Add to your Cargo.toml:

async-mailer = "0.4.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::Secret::new("<OAuth2 app secret>".into())
).await?;

// Alternative:

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

// 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::Secret::new("<OAuth2 app secret>".into())
).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::Secret::new("<password>".into())
);

// 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

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

Enums

Traits

Type Aliases