#email #mime #mail #e-mail

mail-builder

E-mail builder library for Rust

6 releases

0.2.1 Aug 2, 2022
0.2.0 May 20, 2022
0.1.3 Feb 16, 2022
0.1.2 Jan 26, 2022

#21 in Email

Download history 37/week @ 2022-04-24 48/week @ 2022-05-01 64/week @ 2022-05-08 130/week @ 2022-05-15 71/week @ 2022-05-22 68/week @ 2022-05-29 71/week @ 2022-06-05 39/week @ 2022-06-12 35/week @ 2022-06-19 26/week @ 2022-06-26 50/week @ 2022-07-03 38/week @ 2022-07-10 39/week @ 2022-07-17 29/week @ 2022-07-24 56/week @ 2022-07-31 65/week @ 2022-08-07

189 downloads per month
Used in mail-send

Apache-2.0 OR MIT

90KB
1.5K SLoC

mail-builder

crates.io build docs.rs crates.io

mail-builder is a flexible e-mail builder library written in Rust. It includes the following features:

  • Generates e-mail messages conforming to the Internet Message Format standard (RFC 5322).
  • Full MIME support (RFC 2045 - 2049) with automatic selection of the most optimal encoding for each message body part.
  • Fast Base64 encoding based on Chromium's decoder (the fastest non-SIMD encoder).
  • Minimal dependencies.

Please note that this library does not support sending or parsing e-mail messages as these functionalities are provided by the crates mail-send and mail-parser.

Usage Example

Build a simple e-mail message with a text body and one attachment:

    // Build a simple text message with a single attachment
    let eml = MessageBuilder::new()
        .from(("John Doe", "john@doe.com"))
        .to("jane@doe.com")
        .subject("Hello, world!")
        .text_body("Message contents go here.")
        .binary_attachment("image/png", "image.png", [1, 2, 3, 4].as_ref())
        .write_to_string()
        .unwrap();
        
    // Print raw message
    println!("{}", eml);

More complex messages with grouped addresses, inline parts and multipart/alternative sections can also be easily built:

    // Build a multipart message with text and HTML bodies,
    // inline parts and attachments.
    MessageBuilder::new()
        .from(("John Doe", "john@doe.com"))

        // To recipients
        .to(vec![
            ("Antoine de Saint-Exupéry", "antoine@exupery.com"),
            ("안녕하세요 세계", "test@test.com"),
            ("Xin chào", "addr@addr.com"),
        ])

        // BCC recipients using grouped addresses
        .bcc(vec![
            (
                "My Group",
                vec![
                    ("ASCII name", "addr1@addr7.com"),
                    ("ハロー・ワールド", "addr2@addr6.com"),
                    ("áéíóú", "addr3@addr5.com"),
                    ("Γειά σου Κόσμε", "addr4@addr4.com"),
                ],
            ),
            (
                "Another Group",
                vec![
                    ("שלום עולם", "addr5@addr3.com"),
                    ("ñandú come ñoquis", "addr6@addr2.com"),
                    ("Recipient", "addr7@addr1.com"),
                ],
            ),
        ])

        // Set RFC and custom headers
        .subject("Testing multipart messages") 
        .in_reply_to(vec!["message-id-1", "message-id-2"])
        .header("List-Archive", URL::new("http://example.com/archive"))

        // Set HTML and plain text bodies
        .text_body("This is the text body!\n") 
        .html_body("<p>HTML body with <img src=\"cid:my-image\"/>!</p>") 

        // Include an embedded image as an inline part
        .binary_inline("image/png", "cid:my-image", [0, 1, 2, 3, 4, 5].as_ref())
        .text_attachment("text/plain", "my fíle.txt", "Attachment contents go here.") 

        // Add text and binary attachments
        .binary_attachment(
            "text/plain",
            "ハロー・ワールド",
            b"Binary contents go here.".as_ref(),
        )

        // Write the message to a file
        .write_to(File::create("message.eml").unwrap())
        .unwrap();

Nested MIME body structures can be created using the body method:

    // Build a nested multipart message
    MessageBuilder::new()
        .from(Address::new_address("John Doe".into(), "john@doe.com"))
        .to(Address::new_address("Jane Doe".into(), "jane@doe.com"))
        .subject("Nested multipart message")

        // Define the nested MIME body structure
        .body(MimePart::new_multipart(
            "multipart/mixed",
            vec![
                MimePart::new_text("Part A contents go here...").inline(),
                MimePart::new_multipart(
                    "multipart/mixed",
                    vec![
                        MimePart::new_multipart(
                            "multipart/alternative",
                            vec![
                                MimePart::new_multipart(
                                    "multipart/mixed",
                                    vec![
                                        MimePart::new_text("Part B contents go here...").inline(),
                                        MimePart::new_binary(
                                            "image/jpeg",
                                            "Part C contents go here...".as_bytes(),
                                        )
                                        .inline(),
                                        MimePart::new_text("Part D contents go here...").inline(),
                                    ],
                                ),
                                MimePart::new_multipart(
                                    "multipart/related",
                                    vec![
                                        MimePart::new_html("Part E contents go here...").inline(),
                                        MimePart::new_binary(
                                            "image/jpeg",
                                            "Part F contents go here...".as_bytes(),
                                        ),
                                    ],
                                ),
                            ],
                        ),
                        MimePart::new_binary("image/jpeg", "Part G contents go here...".as_bytes())
                            .attachment("image_G.jpg"),
                        MimePart::new_binary(
                            "application/x-excel",
                            "Part H contents go here...".as_bytes(),
                        ),
                        MimePart::new_binary(
                            "x-message/rfc822",
                            "Part J contents go here...".as_bytes(),
                        ),
                    ],
                ),
                MimePart::new_text("Part K contents go here...").inline(),
            ],
        ))
        
        // Write the message to a file
        .write_to(File::create("nested-message.eml").unwrap())
        .unwrap();

Testing

To run the testsuite:

 $ cargo test --all-features

or, to run the testsuite with MIRI:

 $ cargo +nightly miri test --all-features

License

Licensed under either of

at your option.

Copyright

Copyright (C) 2020-2022, Stalwart Labs Ltd.

See COPYING for the license.

Dependencies

~1MB
~16K SLoC