Polymail

Unified email sending interface for Rust. Write your email once, send it through any supported provider — swap providers by changing one line.

Currently supported: Lettermint, Postmark, SendGrid, and any SMTP server (via lettre).

Usage

[dependencies]
polymail = { version = "0.1", features = ["lettermint"] }
tokio = { version = "1", features = ["rt", "macros"] }

Lettermint is the default feature, so features = ["lettermint"] can be omitted.

Send an email

use polymail::{Email, Body, Mailer};
use polymail::provider::lettermint::LettermintMailer;

#[tokio::main]
async fn main() {
    let mailer = LettermintMailer::new("your-api-token");

    let email = Email::builder("sender@yourdomain.com", "Hello", Body::Text("Hi there!".into()))
        .to("recipient@example.com")
        .build()
        .unwrap();

    let result = mailer.send(&email).await.unwrap();
    println!("Sent: {:?}", result.message_id);
}

HTML + text with all options

use polymail::{Email, Body, Address, Attachment, Mailer};
use polymail::provider::lettermint::LettermintMailer;

async fn send_full(mailer: &LettermintMailer) {
    let email = Email::builder(
            Address::with_name("jane@yourdomain.com", "Jane"),
            "Monthly update",
            Body::Both {
                html: "<h1>Update</h1><p>Here's what happened.</p>".into(),
                text: "Here's what happened.".into(),
            },
        )
        .to("user@example.com")
        .cc("team@example.com")
        .bcc("archive@example.com")
        .reply_to("support@yourdomain.com")
        .header("X-Campaign", "monthly-update")
        .attachment(Attachment {
            filename: "report.pdf".into(),
            content: "<base64-encoded-content>".into(),
            content_type: "application/pdf".into(),
            content_id: None,
        })
        .tag("newsletter")
        .metadata("campaign_id", "2025-03")
        .build()
        .unwrap();

    let result = mailer.send(&email).await.unwrap();
    println!("{:?}", result);
}

Batch sending

Providers with native batch support send all emails in a single API call. Others fall back to sequential sends.

use polymail::{Email, Body, BatchItemResult, Mailer};
use polymail::provider::lettermint::LettermintMailer;

async fn send_batch(mailer: &LettermintMailer) {
    let emails: Vec<Email> = vec![
        Email::builder("sender@yourdomain.com", "Hello Alice", Body::Text("Hi Alice!".into()))
            .to("alice@example.com")
            .build()
            .unwrap(),
        Email::builder("sender@yourdomain.com", "Hello Bob", Body::Text("Hi Bob!".into()))
            .to("bob@example.com")
            .build()
            .unwrap(),
    ];

    let results = mailer.batch_send(&emails).await.unwrap();
    for (i, result) in results.iter().enumerate() {
        match result {
            BatchItemResult::Success(r) => println!("#{i}: sent {:?}", r.message_id),
            BatchItemResult::Failed(e) => println!("#{i}: failed {e}"),
        }
    }
}

Switching providers

use polymail::{Email, Body, Mailer};
use polymail::provider::postmark::PostmarkMailer;

let mailer = PostmarkMailer::new("your-server-token");
// Same Email, same .send() call — just a different mailer.

SMTP (any server)

The smtp feature sends through any SMTP server via lettre. Pick the transport security with SmtpTls (Implicit for port 465, StartTls for 587, None for plaintext).

use polymail::{Email, Body, Mailer};
use polymail::provider::smtp::{SmtpMailer, SmtpTls};

async fn send_smtp() {
    // Production relay with STARTTLS + auth:
    let mailer = SmtpMailer::builder("smtp.example.com")
        .tls(SmtpTls::StartTls)
        .credentials("user", "pass")
        .build()
        .unwrap();

    // Or a local sink for testing (plaintext, no auth), e.g. mailcrab or MailHog:
    let mailer = SmtpMailer::plaintext("localhost", 1025);

    let email = Email::builder("sender@example.com", "Hello", Body::Text("Hi there!".into()))
        .to("recipient@example.com")
        .build()
        .unwrap();

    mailer.send(&email).await.unwrap();
}

For custom trust roots, pool tuning, or alternate auth mechanisms, build a lettre AsyncSmtpTransport yourself and pass it to SmtpMailer::with_transport.

Fallback across providers

FallbackMailer tries providers in order. On transient failures (network issues, rate limits, service outages), it moves to the next provider. On permanent failures (invalid address, hard bounce), it returns immediately — retrying won't help.

use polymail::{FallbackMailer, Mailer};
use polymail::provider::lettermint::LettermintMailer;
use polymail::provider::smtp::{SmtpMailer, SmtpTls};

let mailer = FallbackMailer::new(vec![
    Box::new(LettermintMailer::new("lettermint-token")),
    Box::new(
        SmtpMailer::builder("smtp.example.com")
            .tls(SmtpTls::StartTls)
            .credentials("user", "pass")
            .build()?,
    ),
]);

// Tries the Lettermint API first; if it's down (or rate-limited),
// falls back to your own SMTP relay.
let result = mailer.send(&email).await?;

FallbackMailer implements Mailer, so it works anywhere a single provider does — including Box<dyn Mailer>.

Errors that trigger fallback:

Using as a trait object

use polymail::Mailer;
use polymail::provider::lettermint::LettermintMailer;

fn get_mailer() -> Box<dyn Mailer> {
    Box::new(LettermintMailer::new("token"))
}

Features

Enable multiple providers at once:

polymail = { version = "0.1", features = ["lettermint", "postmark"] }

Provider capabilities

SMTP has no side channel for tags or metadata: anything added would become recipient-visible headers logged by every relay in between, so both are dropped. Explicit .header(...) values are still sent.

Batch size for SMTP is unbounded by polymail (sends are sequential over one pooled connection), but real servers may throttle or greylist after N messages per session.

The smtp feature uses rustls with bundled webpki-roots, not the system trust store. For corporate or system CAs, build your own AsyncSmtpTransport and pass it to SmtpMailer::with_transport.

Error handling

Provider-specific errors are mapped to shared SendError variants so you can handle common failure modes without matching on providers:

use polymail::{Mailer, SendError};

match mailer.send(&email).await {
    Ok(result) => println!("sent: {:?}", result.message_id),
    Err(SendError::RateLimitExceeded(_)) => println!("back off and retry"),
    Err(SendError::Authentication(_)) => println!("check your API key"),
    Err(SendError::InvalidAddress(msg)) => println!("bad address: {msg}"),
    Err(e) => println!("other error: {e}"),
}

Error mapping by provider

Testing

cargo test --all-features

The SMTP provider also has integration tests that send through a real SMTP server and assert delivery via its API. They are #[ignore]-d by default; CI runs them against a mailcrab service container. To run them locally, start mailcrab and point the tests at it:

docker run --rm -p 1025:1025 -p 1080:1080 marlonb/mailcrab
cargo test --features smtp -- --ignored

Override the defaults with POLYMAIL_SMTP_HOST / POLYMAIL_SMTP_PORT (SMTP) and POLYMAIL_MAILCRAB_API (mailcrab HTTP API base) if the server is elsewhere.

License

Dual-licensed under MIT or Apache 2.0.