مكتبة lettre لـ Rust: إرسال البريد الإلكتروني

1. ما هي ولماذا تستخدمها

lettre (وتعني "رسالة" بالفرنسية) هي مكتبة قوية، غير متزامنة، وآمنة من حيث الأنواع (type-safe) لإرسال البريد الإلكتروني بلغة Rust. توفر مجموعة كاملة من الأدوات لإنشاء وإرسال رسائل البريد الإلكتروني، مع دعم كل من الرسائل النصية البسيطة ورسائل HTML المعقدة مع المرفقات. المكتبة مكتوبة بلغة Rust الخالصة دون اعتماديات خارجية على مستوى النظام، مما يجعلها الخيار الأمثل للمشاريع التي تتطلب قابلية النقل والأمان.

لماذا تحتاج إلى lettre؟ في تطوير الويب الحديث، يظل إرسال البريد الإلكتروني وظيفة حيوية: تسجيل المستخدمين، إعادة تعيين كلمات المرور، الإشعارات، النشرات البريدية. Rust، باعتبارها لغة نظام، لم تكن تمتلك تقليديًا أدوات سهلة للتعامل مع البريد. lettre تسد هذه الفجوة، وتقدم واجهة برمجية أنيقة، ودعمًا كاملاً لمعايير SMTP وMIME وSSL/TLS، بالإضافة إلى التكامل مع بيئات التشغيل غير المتزامنة الشهيرة (tokio, async-std).

تشمل الإمكانيات الرئيسية للمكتبة: دعم SMTP وSMTPS وSMTP عبر STARTTLS؛ إنشاء رسائل MIME متعددة الأجزاء مع المرفقات؛ العمل مع أجزاء HTML والنص؛ دعم الإرسال غير المتزامن؛ الترميز التلقائي للمرفقات والعناوين؛ والأمان الكامل للأنواع في مرحلة الترجمة، مما يمنع العديد من الأخطاء الشائعة في اللغات الديناميكية.

2. التثبيت

لتثبيت مكتبة lettre، أضفها إلى ملف Cargo.toml الخاص بمشروعك:

[dependencies]
lettre = "0.11"

للعمل غير المتزامن مع tokio (موصى به):

[dependencies]
lettre = { version = "0.11", features = ["tokio1-rustls-tls", "builder"] }
tokio = { version = "1", features = ["full"] }

للعمل المتزامن (بدون بيئة تشغيل غير متزامنة):

[dependencies]
lettre = { version = "0.11", features = ["rustls-tls", "builder"] }

بعد إضافة التبعيات، قم بتنفيذ الأمر:

cargo build

3. البداية السريعة

مثال عملي بسيط لإرسال بريد إلكتروني عبر خادم SMTP لجيميل:

use lettre::message::header::ContentType;
use lettre::transport::smtp::authentication::Credentials;
use lettre::{Message, SmtpTransport, Transport};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // إنشاء الرسالة
    let email = Message::builder()
        .from("المرسل <your_email@gmail.com>".parse()?)
        .to("المستلم <recipient@example.com>".parse()?)
        .subject("مرحباً من Rust!")
        .header(ContentType::TEXT_PLAIN)
        .body("هذه رسالة اختبارية تم إرسالها باستخدام lettre.".to_string())?;

    // إعداد نقل SMTP
    let creds = Credentials::new(
        "your_email@gmail.com".to_string(),
        "your_app_password".to_string() // استخدم كلمة مرور التطبيق
    );

    let mailer = SmtpTransport::relay("smtp.gmail.com")?
        .credentials(creds)
        .build();

    // الإرسال
    match mailer.send(&email) {
        Ok(_) => println!("تم إرسال البريد بنجاح!"),
        Err(e) => eprintln!("خطأ في الإرسال: {:?}", e),
    }

    Ok(())
}

4. الطرق والهياكل الأساسية

4.1. Message::builder()

التوقيع: pub fn builder() -> MessageBuilder

الوصف: ينشئ منشئًا جديدًا (builder) لبناء رسالة بريد إلكتروني. يتيح لك المنشئ تحديد جميع معلمات الرسالة بشكل متسلسل: المرسل، المستلمين، الموضوع، المحتوى، والعناوين.

use lettre::Message;

let email = Message::builder()
    .from("user@example.com".parse()?)
    .to("recipient@example.com".parse()?)
    .subject("اختبار")
    .body("مرحباً!".to_string())?;

4.2. MessageBuilder::to()

التوقيع: pub fn to(self, addr: Address) -> MessageBuilder

الوصف: يضيف مستلمًا إلى الرسالة. يمكن استدعاء هذه الطريقة عدة مرات لإضافة مستلمين متعددين. تقبل الطريقة عنوان بريد إلكتروني صالحًا ويتم التحقق من صحته في وقت الترجمة.

let email = Message::builder()
    .from("sender@example.com".parse()?)
    .to("recipient1@example.com".parse()?)
    .to("recipient2@example.com".parse()?)
    .subject("رسالة لمستلمين متعددين")
    .body("مرحباً بالجميع!".to_string())?;

4.3. SmtpTransport::relay()

التوقيع: pub fn relay(host: &str) -> Result

الوصف: ينشئ موصل SMTP جديد باستخدام خادم بريد معين. هذه هي الطريقة الأكثر شيوعًا لإنشاء موصل SMTP. تقبل اسم المضيف (hostname) لخادم SMTP.

use lettre::transport::smtp::authentication::Credentials;
use lettre::SmtpTransport;

let mailer = SmtpTransport::relay("smtp.gmail.com")?
    .credentials(Credentials::new("user@gmail.com".into(), "password".into()))
    .build();

4.4. SmtpTransport::send()

التوقيع: pub fn send(&self, message: &Message) -> Result

الوصف: يرسل رسالة بريد إلكتروني عبر خادم SMTP المُهيأ. تعيد الطريقة عنوان البريد الإلكتروني للمستلم في حالة النجاح، أو خطأ في حالة الفشل.

match mailer.send(&email) {
    Ok(response) => println!("تم الإرسال إلى: {:?}", response),
    Err(e) => eprintln!("فشل الإرسال: {}", e),
}

5. أمثلة متقدمة

5.1. إرسال بريد HTML مع مرفقات

use lettre::message::header::ContentType;
use lettre::message::{Attachment, MultiPart, SinglePart};
use lettre::{Message, SmtpTransport, Transport};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // إنشاء جزء HTML
    let html_part = SinglePart::builder()
        .header(ContentType::TEXT_HTML)
        .body(String::from(
            "<h1>مرحباً!</h1><p>هذه رسالة HTML من Rust.</p>"
        ));

    // إنشاء مرفق
    let attachment = Attachment::new("document.pdf".into(), 
        std::fs::read("path/to/document.pdf")?,
        ContentType::parse("application/pdf")?);

    // بناء الرسالة متعددة الأجزاء
    let email = Message::builder()
        .from("sender@example.com".parse()?)
        .to("recipient@example.com".parse()?)
        .subject("رسالة HTML مع مرفق")
        .multipart(
            MultiPart::mixed()
                .singlepart(html_part)
                .singlepart(attachment)
        )?;

    // إرسال
    let mailer = SmtpTransport::relay("smtp.gmail.com")?
        .credentials(Credentials::new("user@gmail.com".into(), "password".into()))
        .build();

    mailer.send(&email)?;
    println!("تم إرسال البريد مع المرفق بنجاح!");
    Ok(())
}

5.2. إرسال غير متزامن مع tokio

use lettre::message::header::ContentType;
use lettre::transport::smtp::authentication::Credentials;
use lettre::{AsyncSmtpTransport, Message, Tokio1Executor};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let email = Message::builder()
        .from("sender@example.com".parse()?)
        .to("recipient@example.com".parse()?)
        .subject("إرسال غير متزامن")
        .header(ContentType::TEXT_PLAIN)
        .body("مرحباً من Rust غير المتزامن!".to_string())?;

    let mailer = AsyncSmtpTransport::<Tokio1Executor>::relay("smtp.gmail.com")?
        .credentials(Credentials::new("user@gmail.com".into(), "password".into()))
        .build();

    match mailer.send(email).await {
        Ok(_) => println!("تم الإرسال غير المتزامن بنجاح!"),
        Err(e) => eprintln!("خطأ: {}", e),
    }

    Ok(())
}

6. الخلاصة

مكتبة lettre هي أداة قوية وموثوقة لإرسال البريد الإلكتروني في Rust. بفضل تصميمها الآمن من حيث الأنواع ودعمها الكامل لمعايير البريد الإلكتروني، توفر lettre حلاً مثالياً للمشاريع التي تتطلب إرسال بريد إلكتروني بأمان وكفاءة. سواء كنت تعمل على تطبيق ويب صغير أو نظام معقد، فإن lettre تمنحك المرونة والأدوات اللازمة لإنجاز المهمة.

للمزيد من المعلومات، تفضل بزيارة الوثائق الرسمية أو مستودع GitHub.