Backbone Email

🦴 Production-ready SMTP email service library with template support

Backbone Email is a focused email service library that provides reliable SMTP email functionality with advanced features like template sending, file attachments, and comprehensive error handling. Designed for production use with robust error handling and tracking capabilities.

📋 Table of Contents

• Overview
• Features
• Usage
• SMTP Configuration
• Technical Details
• Examples
• Error Handling
• Testing

🎯 Overview

Backbone Email provides a clean, efficient SMTP email service that handles all common email needs without the complexity of multiple provider abstractions. It's designed for production use with comprehensive error handling and template support.

Key Design Principles

• SMTP Focused: Optimized for reliable SMTP email delivery
• Template Ready: Built-in template rendering with Handlebars
• Production Ready: Robust error handling with retry mechanisms
• Async First: Full async/await support with tokio
• File Attachments: Support for multiple file types and sizes

🚀 Features

📧 Core Email Features

• SMTP Support: Traditional email servers with TLS/SSL support
• Template System: Built-in Handlebars template rendering
• File Attachments: Multiple file attachment support with type detection
• Rich Content: HTML, text, and multipart messages
• Recipient Management: To, CC, and BCC support

🛡️ Production-Ready

• Error Handling: Comprehensive error types with context
• Connection Testing: Pre-flight SMTP connection validation
• Retry Logic: Configurable retry mechanisms for failed deliveries
• Async Operations: Non-blocking email sending and receiving

📊 Message Capabilities

• Multiple Recipients: Send to multiple email addresses
• Custom Headers: Add custom SMTP headers
• Priority Levels: Set message priority (High, Normal, Low)
• Reply-To: Configure reply-to addresses
• Bulk Sending: Send multiple emails efficiently

📖 Usage

Quick Start

[dependencies]
backbone-email = "2.0.0"
tokio = { version = "1.0", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
uuid = { version = "1.0", features = ["v4"] }
chrono = { version = "0.4", features = ["serde"] }

Basic Email Sending

use backbone_email::{EmailService, SmtpProvider, EmailMessage};

// Create SMTP email service
let email_service = SmtpProvider::new("smtp.gmail.com", 587)
    .with_credentials("user@gmail.com", "password")
    .with_tls(true)
    .build()?;

// Create email message
let message = EmailMessage::builder()
    .from("sender@example.com")
    .to("recipient@example.com")
    .subject("Welcome to Backbone Email!")
    .text("This is a plain text email")
    .html("<h1>Welcome!</h1><p>This is HTML content.</p>")
    .build()?;

// Send email
let result = email_service.send(message).await?;
println!("Email sent with message ID: {}", result.message_id);

Template Sending

use backbone_email::{EmailService, SmtpProvider};
use std::collections::HashMap;

// Create email service
let email_service = SmtpProvider::new("smtp.example.com", 587)
    .with_credentials("user", "password")
    .build()?;

// Template data
let mut template_data = HashMap::new();
template_data.insert("name".to_string(), "John Doe".into());
template_data.insert("company".to_string(), "ACME Corp".into());

// Send template email
let result = email_service.send_template(
    "welcome-template",
    vec!["user@example.com"],
    template_data
).await?;

println!("Template email sent: {}", result.message_id);

Email with Attachments

use backbone_email::{EmailService, SmtpProvider, EmailAttachment};

// Create email service
let email_service = SmtpProvider::new("smtp.example.com", 587)
    .with_credentials("user", "password")
    .build()?;

// Create attachment
let attachment = EmailAttachment::builder()
    .filename("document.pdf")
    .content(pdf_bytes)
    .content_type("application/pdf")
    .build()?;

// Send email with attachment
let message = EmailMessage::builder()
    .from("sender@example.com")
    .to("recipient@example.com")
    .subject("Document Attached")
    .text("Please find the attached document")
    .attachment(attachment)
    .build()?;

let result = email_service.send(message).await?;
println!("Email with attachment sent: {}", result.message_id);

🔧 SMTP Configuration

Basic Configuration

use backbone_email::SmtpProvider;

// Simple SMTP configuration
let email_service = SmtpProvider::new("smtp.example.com", 587)
    .with_credentials("username", "password")
    .build()?;

Advanced Configuration

use backbone_email::SmtpProvider;

// Advanced SMTP configuration with TLS and custom settings
let email_service = SmtpProvider::new("smtp.gmail.com", 587)
    .with_credentials("user@gmail.com", "app_password")
    .with_tls(true)
    .with_timeout(30)
    .with_connection_pool_size(5)
    .with_default_sender("notifications@company.com")
    .build()?;

Common SMTP Providers

Gmail/Google Workspace

let email_service = SmtpProvider::new("smtp.gmail.com", 587)
    .with_credentials("user@company.com", "app_password")
    .with_tls(true)
    .build()?;

Outlook/Office 365

let email_service = SmtpProvider::new("smtp.office365.com", 587)
    .with_credentials("user@company.com", "password")
    .with_tls(true)
    .build()?;

SendGrid

let email_service = SmtpProvider::new("smtp.sendgrid.net", 587)
    .with_credentials("apikey", "YOUR_SENDGRID_API_KEY")
    .with_tls(true)
    .build()?;

🔧 Technical Details

Core Traits

EmailService Trait

#[async_trait]
pub trait EmailService: Send + Sync {
    async fn send(&self, message: EmailMessage) -> EmailResult<EmailDeliveryReport>;
    async fn send_template(
        &self,
        template_name: &str,
        recipients: Vec<String>,
        template_data: HashMap<String, serde_json::Value>,
    ) -> EmailResult<EmailDeliveryReport>;

    async fn test_connection(&self) -> EmailResult<bool>;
    async fn validate_config(&self) -> EmailResult<bool>;
}

Message Types

EmailMessage

pub struct EmailMessage {
    pub from: String,
    pub to: Vec<String>,
    pub cc: Vec<String>,
    pub bcc: Vec<String>,
    pub subject: String,
    pub text_content: Option<String>,
    pub html_content: Option<String>,
    pub attachments: Vec<EmailAttachment>,
    pub headers: HashMap<String, String>,
    pub reply_to: Option<String>,
    pub priority: EmailPriority,
}

EmailDeliveryReport

pub struct EmailDeliveryReport {
    pub message_id: String,
    pub status: EmailStatus,
    pub provider_message_id: Option<String>,
    pub delivered_at: Option<DateTime<Utc>>,
    pub error: Option<String>,
    pub bounce_reason: Option<String>,
}

Error Handling

#[derive(Debug, thiserror::Error)]
pub enum EmailError {
    #[error("SMTP connection error: {0}")]
    SmtpConnection(String),

    #[error("SMTP authentication error: {0}")]
    SmtpAuth(String),

    #[error("SMTP send error: {0}")]
    SmtpSend(String),

    #[error("Template rendering error: {0}")]
    TemplateError(String),

    #[error("Invalid email address: {0}")]
    InvalidEmail(String),

    #[error("Attachment error: {0}")]
    AttachmentError(String),

    #[error("Configuration error: {0}")]
    ConfigError(String),
}

📚 Examples

1. Welcome Email Service

use backbone_email::{EmailService, SmtpProvider};
use std::collections::HashMap;

async fn send_welcome_email(email_service: &dyn EmailService, user_email: &str, user_name: &str) -> Result<(), Box<dyn std::error::Error>> {
    let mut template_data = HashMap::new();
    template_data.insert("name".to_string(), user_name.into());
    template_data.insert("email".to_string(), user_email.into());

    let report = email_service.send_template(
        "welcome-email",
        vec![user_email],
        template_data
    ).await?;

    println!("Welcome email sent to {}: {}", user_email, report.message_id);
    Ok(())
}

2. Bulk Email Newsletter

use backbone_email::{EmailService, SmtpProvider, EmailMessage};

async fn send_newsletter(
    email_service: &dyn EmailService,
    subscribers: Vec<String>,
    subject: &str,
    content: &str
) -> Result<usize, Box<dyn std::error::Error>> {
    let mut sent_count = 0;

    for subscriber in subscribers {
        let message = EmailMessage::builder()
            .from("newsletter@company.com")
            .to(subscriber.clone())
            .subject(subject)
            .html(content)
            .build()?;

        match email_service.send(message).await {
            Ok(_) => {
                sent_count += 1;
                println!("Newsletter sent to {}", subscriber);
            }
            Err(e) => {
                eprintln!("Failed to send to {}: {}", subscriber, e);
            }
        }
    }

    println!("Newsletter sent to {} subscribers", sent_count);
    Ok(sent_count)
}

3. Email Service Health Check

use backbone_email::EmailService;

async fn check_email_health(email_service: &dyn EmailService) -> Result<bool, Box<dyn std::error::Error>> {
    // Test configuration
    if !email_service.validate_config().await? {
        println!("❌ Email service configuration is invalid");
        return Ok(false);
    }

    // Test connection
    if !email_service.test_connection().await? {
        println!("❌ Email service connection failed");
        return Ok(false);
    }

    println!("✅ Email service is healthy");
    Ok(true)
}

🔧 Error Handling

Error Recovery

use backbone_email::{EmailService, EmailError};

async fn send_with_retry(
    email_service: &dyn EmailService,
    message: backbone_email::EmailMessage,
    max_retries: u32
) -> Result<backbone_email::EmailDeliveryReport, Box<dyn std::error::Error>> {
    let mut retries = 0;

    loop {
        match email_service.send(message.clone()).await {
            Ok(report) => return Ok(report),
            Err(EmailError::SmtpSend(err)) if retries < max_retries => {
                retries += 1;
                println!("Send failed (attempt {}), retrying: {}", retries, err);
                tokio::time::sleep(tokio::time::Duration::from_secs(2_u64.pow(retries))).await;
            }
            Err(e) => return Err(e.into()),
        }
    }
}

🧪 Testing

Unit Tests

# Run all backbone-email tests
cargo test --package backbone-email

# Run specific tests
cargo test --package backbone-email -- -- smtp
cargo test --package backbone-email -- -- template

Mock Testing

use backbone_email::{EmailService, EmailMessage, EmailDeliveryReport};
use std::collections::HashMap;

struct MockEmailService {
    should_fail: bool,
}

#[async_trait]
impl EmailService for MockEmailService {
    async fn send(&self, message: EmailMessage) -> backbone_email::EmailResult<EmailDeliveryReport> {
        if self.should_fail {
            Err(backbone_email::EmailError::SmtpSend("Mock failure".to_string()))
        } else {
            Ok(EmailDeliveryReport {
                message_id: "mock-123".to_string(),
                status: backbone_email::EmailStatus::Sent,
                provider_message_id: Some("mock-id-123".to_string()),
                delivered_at: Some(chrono::Utc::now()),
                error: None,
                bounce_reason: None,
            })
        }
    }

    // Implement other required methods...
}

🔗 Configuration

Environment Variables

# SMTP Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=user@gmail.com
SMTP_PASSWORD=app_password
SMTP_USE_TLS=true
SMTP_DEFAULT_SENDER=notifications@company.com

YAML Configuration

# backbone-email configuration
email:
  provider: "smtp"

  smtp:
    host: "${SMTP_HOST}"
    port: ${SMTP_PORT}
    username: "${SMTP_USERNAME}"
    password: "${SMTP_PASSWORD}"
    use_tls: ${SMTP_USE_TLS}
    timeout: 30
    connection_pool_size: 5

  # Template settings
  templates:
    engine: "handlebars"
    directory: "./templates"

  # Default settings
  defaults:
    sender: "${SMTP_DEFAULT_SENDER}"
    priority: "normal"

📊 Performance Considerations

Connection Pooling

// Reuse the email service instance
let email_service = Arc::new(
    SmtpProvider::new("smtp.gmail.com", 587)
        .with_credentials("user", "password")
        .with_connection_pool_size(10)
        .build()?
);

// Thread-safe usage across multiple tasks
for i in 0..100 {
    let service = email_service.clone();
    tokio::spawn(async move {
        let message = EmailMessage::builder()
            .from("test@example.com")
            .to(format!("user{}@example.com", i))
            .subject(format!("Test Email {}", i))
            .text("This is a test email")
            .build()?;

        let _ = service.send(message).await;
    });
}

🔄 Version History

Current Version: 2.0.0

Features:

• ✅ SMTP email delivery with TLS support
• ✅ Handlebars template rendering
• ✅ File attachment support
• ✅ Connection testing and validation
• ✅ Comprehensive error handling
• ✅ Async/await support
• ✅ Builder pattern configuration

Breaking Changes from v1.x:

• Simplified to SMTP-only implementation
• Updated API to use builder patterns
• Enhanced error handling with context
• Removed multi-provider complexity

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• Backbone Core - Generic CRUD foundation
• Backbone CLI - Code generation tools
• Backbone Storage - File storage services
• Framework Documentation - Complete framework guide

🦴 Backbone Email - Simple, reliable SMTP email delivery

SMTP Focused • Template Ready • Production Ready