Rust邮件构建库mail-builder使用指南

mail-builder是一个用于构建和解析符合RFC标准电子邮件的Rust库。它提供了简单直观的API来创建各种类型的电子邮件，包括文本邮件、HTML邮件以及带附件的多部分邮件。

基本用法

首先在Cargo.toml中添加依赖：

[dependencies]
mail-builder = "0.3"

创建简单文本邮件

use mail_builder::MessageBuilder;

// 创建一个简单的文本邮件
let email = MessageBuilder::new()
    .from("John Doe <john@example.com>")  // 设置发件人
    .to("Jane Smith <jane@example.com>")  // 设置收件人
    .subject("Hello from Rust!")          // 设置邮件主题
    .text_body("This is a plain text email body.")  // 设置纯文本正文
    .build()
    .unwrap();

println!("{}", email);  // 打印生成的邮件内容

创建HTML邮件

// 创建一个HTML格式的邮件
let email = MessageBuilder::new()
    .from("John Doe <john@example.com>")
    .to("Jane Smith <jane@example.com>")
    .subject("HTML Email")
    .html_body("<h1>Hello!</h1><p>This is an <strong>HTML</strong> email.</p>")  // 设置HTML正文
    .build()
    .unwrap();

创建带附件的邮件

use mail_builder::headers::content_type::MediaType;
use std::fs;

// 读取附件文件内容
let attachment_data = fs::read("document.pdf").unwrap();

// 创建带附件的邮件
let email = MessageBuilder::new()
    .from("sender@example.com")
    .to("recipient@example.com")
    .subject("Email with attachment")
    .text_body("Please see the attached document.")
    .binary_attachment(
        MediaType::parse("application/pdf").unwrap(),  // 设置附件MIME类型
        "document.pdf",  // 设置附件文件名
        &attachment_data,  // 设置附件数据
    )
    .build()
    .unwrap();

创建多部分邮件(文本+HTML+附件)

// 创建包含文本、HTML和附件的多部分邮件
let email = MessageBuilder::new()
    .from("sender@example.com")
    .to("recipient@example.com")
    .subject("Multipart email")
    .text_body("This is the plain text version.")  // 纯文本版本
    .html_body("<h1>HTML version</h1><p>This is the HTML version.</p>")  // HTML版本
    .binary_attachment(
        MediaType::parse("application/pdf").unwrap(),
        "document.pdf",
        &attachment_data,
    )
    .build()
    .unwrap();

解析邮件

mail-builder也可以用于解析现有的电子邮件：

use mail_parser::Message;

// 原始邮件字符串
let raw_email = "From: sender@example.com\r\n\
                To: recipient@example.com\r\n\
                Subject: Test\r\n\
                \r\n\
                This is the body";

// 解析邮件
let message = Message::parse(raw_email.as_bytes()).unwrap();

// 打印解析结果
println!("From: {:?}", message.from());
println!("Subject: {:?}", message.subject());
println!("Body: {:?}", message.body_text(0));

高级功能

1. 自定义头信息：

// 添加自定义邮件头
let email = MessageBuilder::new()
    .from("sender@example.com")
    .to("recipient@example.com")
    .header("X-Custom-Header", "Some value")  // 自定义头
    .subject("Custom headers")
    .text_body("This email has custom headers.")
    .build()
    .unwrap();

1. 抄送和密送：

// 设置抄送(CC)和密送(BCC)
let email = MessageBuilder::new()
    .from("sender@example.com")
    .to("primary@example.com")  // 主收件人
    .cc("cc@example.com")       // 抄送
    .bcc("bcc@example.com")     // 密送
    .subject("CC and BCC example")
    .text_body("This email demonstrates CC and BCC.")
    .build()
    .unwrap();

1. 内联图片：

// 读取图片数据
let image_data = fs::read("image.png").unwrap();

// 创建带内联图片的邮件
let email = MessageBuilder::new()
    .from("sender@example.com")
    .to("recipient@example.com")
    .subject("Email with inline image")
    .html_body("<h1>Hello!</h1><img src=\"cid:image1\">")  // 使用cid引用图片
    .inline_binary(
        MediaType::parse("image/png").unwrap(),  // 图片MIME类型
        "image1",  // 图片cid
        &image_data,  // 图片数据
    )
    .build()
    .unwrap();

注意事项

1. 确保所有地址都符合RFC标准格式
2. 对于生产环境，考虑添加DKIM签名和其他安全头信息
3. 大附件可能需要流式处理而不是一次性加载到内存

mail-builder库提供了构建符合RFC标准的电子邮件的强大功能，同时保持了简单易用的API设计。

完整示例代码

以下是一个完整的示例，展示如何使用mail-builder创建并发送一封包含文本、HTML和内联图片的邮件：

use mail_builder::MessageBuilder;
use mail_builder::headers::content_type::MediaType;
use std::fs;

fn main() {
    // 读取图片数据
    let image_data = match fs::read("logo.png") {
        Ok(data) => data,
        Err(e) => {
            eprintln!("Error reading image file: {}", e);
            return;
        }
    };

    // 构建邮件
    let email = MessageBuilder::new()
        .from("Company <noreply@company.com>")
        .to("Customer <customer@example.com>")
        .subject("Your Monthly Newsletter")
        .text_body("Thank you for subscribing to our newsletter!")
        .html_body(r#"
            <h1>Monthly Newsletter</h1>
            <p>Thank you for subscribing to our newsletter!</p>
            <p>Here is our logo: <img src="cid:company_logo"></p>
        "#)
        .inline_binary(
            MediaType::parse("image/png").unwrap(),
            "company_logo",
            &image_data,
        )
        .build()
        .expect("Failed to build email");

    println!("Generated email:\n{}", email);
    
    // 在实际应用中，这里可以添加发送邮件的代码
    // 例如使用SMTP库发送构建好的邮件
}

这个示例展示了如何：

1. 读取本地图片文件作为内联图片
2. 创建包含文本和HTML版本的多部分邮件
3. 在HTML中通过cid引用内联图片
4. 构建完整的邮件内容

在实际应用中，你还需要使用SMTP库(如lettre)来发送构建好的邮件。