mail_struct 0.1.7

A minimalist Rust email structure library with optional support for encoding, decoding, and sending via SMTP. / 一个极简的 Rust 邮件结构库，支持可选的编码、解码及 SMTP 发送功能。
Documentation

English | 中文

mail_struct : Minimalist Email Structure for Rust

mail_struct is a lightweight Rust library designed to define a clear and efficient structure for email messages. It provides optional integration with bitcode for efficient encoding/decoding and mail-send for SMTP transmission, making it a versatile choice for email handling in Rust applications.

Table of Contents

Features

  • Core Structure: Defines Mail and UserMail structs to represent email data.
  • Serialization: Optional encode and decode features using bitcode for high-performance binary serialization.
  • SMTP Integration: Optional send feature to seamlessly convert Mail structs into mail_send::Message for sending.
  • Type Safety: Leverages Rust's type system to ensure data integrity.

Usage

Add mail_struct to your Cargo.toml:

[dependencies]
mail_struct = { version = "0.1.6", features = ["send", "encode", "decode"] }

Creating and Sending an Email

use mail_struct::Mail;
// Assuming you have an SMTP client set up with mail-send
// use mail_send::SmtpClientBuilder;

async fn example() {
    let mail = Mail {
        sender: "sender@example.com".to_string(),
        to_li: vec!["recipient@example.com".to_string()],
        body: b"Hello, this is a test email!".to_vec(),
    };

    // With the 'send' feature enabled, you can convert it to a Message
    // let message = (&mail).into_message().unwrap();
    
    // client.send(message).await.unwrap();
}

Design Philosophy

The library follows a separation of concerns principle. The core lib.rs defines the data structures (Mail, UserMail), keeping the base dependency footprint minimal. Functionalities like serialization and sending are gated behind feature flags (encode, decode, send), allowing users to opt-in only for what they need.

When the send feature is active, the send.rs module provides an implementation of IntoMessage for Mail. This bridges the gap between the raw data structure and the mail-send crate's Message type, facilitating easy SMTP transmission without coupling the core struct tightly to the transport layer.

Tech Stack

  • Rust: Core language.
  • bitcode (Optional): For fast binary encoding and decoding.
  • mail-send (Optional): For SMTP message construction and sending.

Directory Structure

.
├── Cargo.toml          # Project configuration
├── README.md           # Main documentation
├── readme              # Documentation in specific languages
│   ├── en.md           # English README
│   └── zh.md           # Chinese README
├── src
│   ├── lib.rs          # Core struct definitions and feature gates
│   └── send.rs         # SMTP message conversion logic (feature: send)
└── tests
    └── main.rs         # Integration tests

API Documentation

struct Mail

Represents a basic email message.

  • sender: String: The email address of the sender.
  • to_li: Vec<String>: A list of recipient email addresses.
  • body: Vec<u8>: The raw body content of the email.

struct UserMail

A wrapper around Mail associating it with a user ID.

  • mail: Mail: The email content.
  • user_id: u64: The unique identifier of the user associated with this mail.

Historical Context

RFC 822 and the Separation of Envelope and Content

The design of email systems dates back to the early 1980s with the publication of RFC 822 (Standard for the Format of ARPA Internet Text Messages) and RFC 821 (Simple Mail Transfer Protocol). A key architectural decision was the separation of the "envelope" (handled by SMTP for routing) from the "content" (the message headers and body defined by RFC 822).

mail_struct honors this tradition by focusing on the structure of the message (the content), while delegating the transport (the envelope and transmission) to specialized libraries like mail-send. This modular approach mirrors the original design philosophy of the internet's most enduring communication protocol, ensuring flexibility and maintainability.

About

This project is an open-source component of js0.site ⋅ Refactoring the Internet Plan.

We are redefining the development paradigm of the Internet in a componentized way. Welcome to follow us:

mail_struct : 极简 Rust 邮件结构库

mail_struct 是一个轻量级的 Rust 库，旨在为邮件消息定义清晰且高效的结构。它提供了与 bitcode（用于高效编码/解码）和 mail-send（用于 SMTP 传输）的可选集成，使其成为 Rust 应用中处理邮件的灵活选择。

目录

功能特性

  • 核心结构: 定义了 Mail 和 UserMail 结构体来表示邮件数据。
  • 序列化: 通过 encode 和 decode 特性支持使用 bitcode 进行高性能的二进制序列化。
  • SMTP 集成: 可选的 send 特性支持将 Mail 结构体无缝转换为 mail_send::Message 以便发送。
  • 类型安全: 利用 Rust 的类型系统确保数据完整性。

使用指南

在 Cargo.toml 中添加 mail_struct：

[dependencies]
mail_struct = { version = "0.1.6", features = ["send", "encode", "decode"] }

创建并发送邮件

use mail_struct::Mail;
// 假设你已经使用 mail-send 配置好了 SMTP 客户端
// use mail_send::SmtpClientBuilder;

async fn example() {
    let mail = Mail {
        sender: "sender@example.com".to_string(),
        to_li: vec!["recipient@example.com".to_string()],
        body: b"Hello, this is a test email!".to_vec(),
    };

    // 启用 'send' 特性后，可以将其转换为 Message
    // let message = (&mail).into_message().unwrap();
    
    // client.send(message).await.unwrap();
}

设计理念

本库遵循关注点分离原则。核心 lib.rs 定义了数据结构（Mail, UserMail），保持基础依赖最小化。序列化和发送等功能通过特性标志（encode, decode, send）进行门控，允许用户仅按需开启。

当 send 特性激活时，send.rs 模块为 Mail 实现了 IntoMessage trait。这在原始数据结构和 mail-send crate 的 Message 类型之间架起了桥梁，在不将核心结构与传输层紧密耦合的情况下，实现了便捷的 SMTP 传输。

技术栈

  • Rust: 核心开发语言。
  • bitcode (可选): 用于快速二进制编码和解码。
  • mail-send (可选): 用于构建和发送 SMTP 消息。

目录结构

.
├── Cargo.toml          # 项目配置
├── README.md           # 主文档
├── readme              # 多语言文档
│   ├── en.md           # 英文 README
│   └── zh.md           # 中文 README
├── src
│   ├── lib.rs          # 核心结构定义及特性门控
│   └── send.rs         # SMTP 消息转换逻辑 (特性: send)
└── tests
    └── main.rs         # 集成测试

API 文档

struct Mail

表示一个基础的邮件消息。

  • sender: String: 发件人邮箱地址。
  • to_li: Vec<String>: 收件人邮箱地址列表。
  • body: Vec<u8>: 邮件的原始正文内容。

struct UserMail

Mail 的包装器，将其与用户 ID 关联。

  • mail: Mail: 邮件内容。
  • user_id: u64: 与此邮件关联的用户的唯一标识符。

历史背景

RFC 822 与信封/内容的分离

电子邮件系统的设计可以追溯到 20 世纪 80 年代初 RFC 822（ARPA 互联网文本消息格式标准）和 RFC 821（简单邮件传输协议）的发布。一个关键的架构决策是将“信封”（由 SMTP 处理用于路由）与“内容”（由 RFC 822 定义的消息头和正文）分离开来。

mail_struct 秉承了这一传统，专注于消息的结构（内容），而将传输（信封和发送）委托给像 mail-send 这样的专用库。这种模块化的方法反映了互联网最持久通信协议的原始设计哲学，确保了灵活性和可维护性。

关于

本项目为 js0.site ⋅ 重构互联网计划 的开源组件。

我们正在以组件化的方式重新定义互联网的开发范式，欢迎关注：