Skip to main content

· 4 min read
Mauro D.

Sieve is a language that can be used to create filters for electronic mail. It is not tied to any particular operating system or mail architecture. It requires the use of RFC 822-compliant messages, but otherwise should generalize to other systems that meet these criteria.

Today, the sieve-rs crate was released which is an interpreter for Sieve scripts written in Rust. The interpreter includes support for all existing Sieve extensions.

Currently the interpreter is available as a standalone library but it will be soon added to Stalwart JMAP (including JMAP Sieve support) and Stalwart IMAP (including ManageSieve support).

Compiling and running a Sieve script is straightforward:

    use sieve::{runtime::RuntimeError, Action, Compiler, Event, Input, Runtime};

let text_script = br#"
require ["fileinto", "body", "imap4flags"];

if body :contains "tps" {
setflag "$tps_reports";
}

if header :matches "List-ID" "*<*@*" {
fileinto "INBOX.lists.${2}"; stop;
}
"#;

// Compile
let compiler = Compiler::new();
let script = compiler.compile(text_script).unwrap();

// Build runtime
let runtime = Runtime::new();

// Create filter instance
let mut instance = runtime.filter(
br#"From: Sales Mailing List <[email protected]>
To: John Doe <[email protected]>
List-ID: <[email protected]>
Subject: TPS Reports

We're putting new coversheets on all the TPS reports before they go out now.
So if you could go ahead and try to remember to do that from now on, that'd be great. All right!
"#,
);
let mut input = Input::script("my-script", script);

// Start event loop
while let Some(result) = instance.run(input) {
match result {
Ok(event) => match event {
Event::IncludeScript { name, optional } => {
// NOTE: Just for demonstration purposes, script name needs to be validated first.
if let Ok(bytes) = std::fs::read(name.as_str()) {
let script = compiler.compile(&bytes).unwrap();
input = Input::script(name, script);
} else if optional {
input = Input::False;
} else {
panic!("Script {} not found.", name);
}
}
Event::MailboxExists { .. } => {
// Return true if the mailbox exists
input = false.into();
}
Event::ListContains { .. } => {
// Return true if the list(s) contains an entry
input = false.into();
}
Event::DuplicateId { .. } => {
// Return true if the ID is duplicate
input = false.into();
}
Event::Execute { command, arguments } => {
println!(
"Script executed command {:?} with parameters {:?}",
command, arguments
);
input = false.into(); // Report whether the script succeeded
}
#[cfg(test)]
_ => unreachable!(),
},
Err(error) => {
match error {
RuntimeError::IllegalAction => {
eprintln!("Script tried allocating more variables than allowed.");
}
RuntimeError::TooManyIncludes => {
eprintln!("Too many included scripts.");
}
RuntimeError::InvalidInstruction(instruction) => {
eprintln!(
"Invalid instruction {:?} found at {}:{}.",
instruction.name(),
instruction.line_num(),
instruction.line_pos()
);
}
RuntimeError::ScriptErrorMessage(message) => {
eprintln!("Script called the 'error' function with {:?}", message);
}
RuntimeError::CapabilityNotAllowed(capability) => {
eprintln!(
"Capability {:?} has been disabled by the administrator.",
capability
);
}
RuntimeError::CapabilityNotSupported(capability) => {
eprintln!("Capability {:?} not supported.", capability);
}
RuntimeError::OutOfMemory => {
eprintln!("Script exceeded the configured memory limit.");
}
RuntimeError::CPULimitReached => {
eprintln!("Script exceeded the configured CPU limit.");
}
}
break;
}
}
}

// Process actions
for action in instance.get_actions() {
match action {
Action::Keep { flags, message_id } => {
println!(
"Keep message '{}' with flags {:?}.",
std::str::from_utf8(instance.get_message(*message_id).unwrap()).unwrap(),
flags
);
}
Action::Discard => {
println!("Discard message.")
}
Action::Reject { reason } => {
println!("Reject message with reason {:?}.", reason);
}
Action::Ereject { reason } => {
println!("Ereject message with reason {:?}.", reason);
}
Action::FileInto {
folder,
flags,
message_id,
..
} => {
println!(
"File message '{}' in folder {:?} with flags {:?}.",
std::str::from_utf8(instance.get_message(*message_id).unwrap()).unwrap(),
folder,
flags
);
}
Action::SendMessage {
recipient,
message_id,
..
} => {
println!(
"Send message '{}' to {:?}.",
std::str::from_utf8(instance.get_message(*message_id).unwrap()).unwrap(),
recipient
);
}
Action::Notify {
message, method, ..
} => {
println!("Notify URI {:?} with message {:?}", method, message);
}
}
}

Additional examples are available on the repository.

· One min read
Mauro D.

We are happy to announce Stalwart JMAP, an open-source JSON Meta Application Protocol server written in Rust that aims to be scalable, robust and secure.

Some of its key features are:

  • JMAP Core, JMAP Mail and JMAP over WebSocket full compliance.
  • IMAP4 rev2/1 support via Stalwart IMAP, an imap-to-jmap proxy.
  • Scalable and fault tolerant: consensus over Raft, node autodiscovery over gossip and read-only replicas.
  • RocksDB backend with full-text search support in 17 languages.
  • OAuth 2.0 authorization code and device authorization flows.
  • Domain Keys Identified Mail (DKIM) message signing.
  • Written in Rust.
  • No third-party software required to run or scale.

Currently Stalwart JMAP requires an SMTP server such as Postfix in order to receive e-mails. However, the next item on the roadmap is to release an SMTP server in Rust with the goal of making self-hosting an e-mail server much simpler without sacrificing any security.

· 2 min read
Mauro D.

Building and sending e-mails securely does not have to be complicated. Today the mail-send crate was released including the following features:

  • Generates e-mail messages conforming to the Internet Message Format standard (RFC 5322) with full MIME support (RFC 2045–2049) and automatic selection of the most optimal encoding for each message body part.
  • DomainKeys Identified Mail (DKIM) Signatures (RFC 6376).
  • SMTP support with TLS and multiple authentication mechanisms (XOAUTH2, CRAM-MD5, DIGEST-MD5, LOGIN and PLAIN).
  • Full async (requires Tokio).

Composing and sending an e-mail message via SMTP is as simple as:

        // Build a simple multipart message
let message = MessageBuilder::new()
.from(("John Doe", "[email protected]"))
.to(vec![
("Jane Doe", "[email protected]"),
("James Smith", "[email protected]"),
])
.subject("Hi!")
.html_body("<h1>Hello, world!</h1>")
.text_body("Hello world!");

// Connect to an SMTP relay server over TLS and
// authenticate using the provided credentials.
Transport::new("smtp.gmail.com")
.credentials("john", "p4ssw0rd")
.connect_tls()
.await
.unwrap()
.send(message)
.await
.unwrap();

And to sign a message with DKIM just do:

    // Build a simple text message with a single attachment
let message = MessageBuilder::new()
.from(("John Doe", "[email protected]"))
.to("[email protected]")
.subject("Howdy!")
.text_body("These pretzels are making me thirsty.")
.binary_attachment("image/png", "pretzels.png", [1, 2, 3, 4].as_ref());

// Set up DKIM signer
let dkim = DKIM::from_pkcs1_pem_file("./cert.pem")
.unwrap()
.domain("example.com")
.selector("2022")
.headers(["From", "To", "Subject"]) // Headers to sign
.expiration(60 * 60 * 7); // Number of seconds before this signature expires (optional)

// Connect to an SMTP relay server over TLS.
// Signs each message with the configured DKIM signer.
Transport::new("smtp.example.com")
.dkim(dkim)
.connect_tls()
.await
.unwrap()
.send(message)
.await
.unwrap();

More examples can be found on Github. Enjoy DKIM signing!

· 3 min read
Mauro D.

Back in November we released mail-parser, a Rust library to parse MIME e-mail messages of any complexity. Today we are proud to announce the release of mail-builder, a simple yet powerful library to build RFC5322 e-mail messages with MIME support.

Using mail-builder is straightforward:

        // Build a simple text message with a single attachment
let mut message = MessageBuilder::new();
message.from(("John Doe", "[email protected]"));
message.to("[email protected]");
message.subject("Hello, world!");
message.text_body("Message contents go here.");
message.binary_attachment("image/png", "image.png", &[1, 2, 3, 4]);

// Write message to memory
let mut output = Vec::new();
message.write_to(&mut output).unwrap();

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.
let mut message = MessageBuilder::new();
message.from(("John Doe", "[email protected]"));

// To recipients
message.to(vec![
("Antoine de Saint-Exupéry", "[email protected]"),
("안녕하세요 세계", "[email protected]"),
("Xin chào", "[email protected]"),
]);

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

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

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

// Include an embedded image as an inline part
message.binary_inline("image/png", "cid:my-image", &[0, 1, 2, 3, 4, 5]);

// Add a text and a binary attachment
message.text_attachment("text/plain", "my fíle.txt", "Attachment contents go here.");
message.binary_attachment(
"text/plain",
"ハロー・ワールド",
b"Binary contents go here.",
);

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

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

    // Build a nested multipart message
let mut message = MessageBuilder::new();

message.from(Address::new_address("John Doe".into(), "[email protected]"));
message.to(Address::new_address("Jane Doe".into(), "[email protected]"));
message.subject("Nested multipart message");

// Define the nested MIME body structure
message.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
message
.write_to(File::create("nested-message.eml").unwrap())
.unwrap();

The library is available at https://crates.io/crates/mail-builder and the documentation at https://docs.rs/mail-builder.

· 5 min read
Mauro D.

Today we released mail-parser, an e-mail parsing library written in Rust that fully conforms to the Internet Message Format standard (RFC 5322), the Multipurpose Internet Mail Extensions (MIME; RFC 2045–2049) as well as other internet messaging RFCs.

It also supports decoding messages in 41 different character sets including obsolete formats such as UTF-7. All Unicode (UTF-*) and single-byte character sets are handled internally by the library while support for legacy multi-byte encodings of Chinese and Japanese languages such as BIG5 or ISO-2022-JP is provided by the optional dependency encoding_rs.

In general, this library abides by the Postel’s law or Robustness Principle which states that an implementation must be conservative in its sending behavior and liberal in its receiving behavior. This means that mail-parser will make a best effort to parse non-conformant e-mail messages as long as these do not deviate too much from the standard.

Unlike other e-mail parsing libraries that return nested representations of the different MIME parts in a message, this library conforms to RFC 8621, Section 4.1.4 and provides a more human-friendly representation of the message contents consisting of just text body parts, html body parts and attachments. Additionally, conversion to/from HTML and plain text inline body parts is done automatically when the alternative version is missing.

Performance and memory safety were two important factors while designing mail-parser:

  • Zero-copy: Practically all strings returned by this library are Cow<str> references to the input raw message.
  • High performance Base64 decoding based on Chromium’s decoder (the fastest non-SIMD decoder).
  • Fast parsing of message header fields, character set names and HTML entities using perfect hashing.
  • Written in 100% safe Rust with no external dependencies.
  • Every function in the library has been fuzzed and meticulously tested with MIRI.
  • Thoroughly battle-tested with millions of real-world e-mail messages dating from 1995 until today.

The library conforms to all internet messaging RFCs:

And supports 41 different character set encodings:

  • UTF-8
  • UTF-16, UTF-16BE, UTF-16LE
  • UTF-7
  • US-ASCII
  • ISO-8859–1
  • ISO-8859–2
  • ISO-8859–3
  • ISO-8859–4
  • ISO-8859–5
  • ISO-8859–6
  • ISO-8859–7
  • ISO-8859–8
  • ISO-8859–9
  • ISO-8859–10
  • ISO-8859–13
  • ISO-8859–14
  • ISO-8859–15
  • ISO-8859–16
  • CP1250
  • CP1251
  • CP1252
  • CP1253
  • CP1254
  • CP1255
  • CP1256
  • CP1257
  • CP1258
  • KOI8-R
  • KOI8_U
  • MACINTOSH
  • IBM850
  • TIS-620
  • SHIFT_JIS
  • BIG5
  • EUC-JP
  • EUC-KR
  • GB18030
  • GBK
  • ISO-2022-JP
  • WINDOWS-874
  • IBM-866

Using the library is straightforward:

    let input = concat!(
"From: Art Vandelay <[email protected]> (Vandelay Industries)\n",
"To: \"Colleagues\": \"James Smythe\" <[email protected]>; Friends:\n",
" [email protected], =?UTF-8?Q?John_Sm=C3=AEth?= <[email protected]>;\n",
"Date: Sat, 20 Nov 2021 14:22:01 -0800\n",
"Subject: Why not both importing AND exporting? =?utf-8?b?4pi6?=\n",
"Content-Type: multipart/mixed; boundary=\"festivus\";\n\n",
"--festivus\n",
"Content-Type: text/html; charset=\"us-ascii\"\n",
"Content-Transfer-Encoding: base64\n\n",
"PGh0bWw+PHA+SSB3YXMgdGhpbmtpbmcgYWJvdXQgcXVpdHRpbmcgdGhlICZsZHF1bztle\n",
"HBvcnRpbmcmcmRxdW87IHRvIGZvY3VzIGp1c3Qgb24gdGhlICZsZHF1bztpbXBvcnRpbm\n",
"cmcmRxdW87LDwvcD48cD5idXQgdGhlbiBJIHRob3VnaHQsIHdoeSBub3QgZG8gYm90aD8\n",
"gJiN4MjYzQTs8L3A+PC9odG1sPg==\n",
"--festivus\n",
"Content-Type: message/rfc822\n\n",
"From: \"Cosmo Kramer\" <[email protected]>\n",
"Subject: Exporting my book about coffee tables\n",
"Content-Type: multipart/mixed; boundary=\"giddyup\";\n\n",
"--giddyup\n",
"Content-Type: text/plain; charset=\"utf-16\"\n",
"Content-Transfer-Encoding: quoted-printable\n\n",
"=FF=FE=0C!5=D8\"=DD5=D8)=DD5=D8-=DD =005=D8*=DD5=D8\"=DD =005=D8\"=\n",
"=DD5=D85=DD5=D8-=DD5=D8,=DD5=D8/=DD5=D81=DD =005=D8*=DD5=D86=DD =\n",
"=005=D8=1F=DD5=D8,=DD5=D8,=DD5=D8(=DD =005=D8-=DD5=D8)=DD5=D8\"=\n",
"=DD5=D8=1E=DD5=D80=DD5=D8\"=DD!=00\n",
"--giddyup\n",
"Content-Type: image/gif; name*1=\"about \"; name*0=\"Book \";\n",
" name*2*=utf-8''%e2%98%95 tables.gif\n",
"Content-Transfer-Encoding: Base64\n",
"Content-Disposition: attachment\n\n",
"R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7\n",
"--giddyup--\n",
"--festivus--\n",
)
.as_bytes();

let message = Message::parse(input);

// Parses addresses (including comments), lists and groups
assert_eq!(
message.get_from(),
&Address::Address(Addr {
name: Some("Art Vandelay (Vandelay Industries)".into()),
address: Some("[email protected]".into())
})
);
assert_eq!(
message.get_to(),
&Address::GroupList(vec![
Group {
name: Some("Colleagues".into()),
addresses: vec![Addr {
name: Some("James Smythe".into()),
address: Some("[email protected]".into())
}]
},
Group {
name: Some("Friends".into()),
addresses: vec![
Addr {
name: None,
address: Some("[email protected]".into())
},
Addr {
name: Some("John Smîth".into()),
address: Some("[email protected]".into())
}
]
}
])
);

assert_eq!(
message.get_date().unwrap().to_iso8601(),
"2021-11-20T14:22:01-08:00"
);

// RFC2047 support for encoded text in message readers
assert_eq!(
message.get_subject().unwrap(),
"Why not both importing AND exporting? ☺"
);

// HTML and text body parts are returned conforming to RFC8621, Section 4.1.4
assert_eq!(
message.get_html_body(0).unwrap().to_string(),
concat!(
"<html><p>I was thinking about quitting the &ldquo;exporting&rdquo; to ",
"focus just on the &ldquo;importing&rdquo;,</p><p>but then I thought,",
" why not do both? &#x263A;</p></html>"
)
);

// HTML parts are converted to plain text (and viceversa) when missing
assert_eq!(
message.get_text_body(0).unwrap().to_string(),
concat!(
"I was thinking about quitting the “exporting” to focus just on the",
" “importing”,\nbut then I thought, why not do both? ☺\n"
)
);

// Supports nested messages as well as multipart/digest
let nested_message = match message.get_attachment(0).unwrap() {
MessagePart::Message(v) => v,
_ => unreachable!(),
};

assert_eq!(
nested_message.get_subject().unwrap(),
"Exporting my book about coffee tables"
);

// Handles UTF-* as well as many legacy encodings
assert_eq!(
nested_message.get_text_body(0).unwrap().to_string(),
"ℌ𝔢𝔩𝔭 𝔪𝔢 𝔢𝔵𝔭𝔬𝔯𝔱 𝔪𝔶 𝔟𝔬𝔬𝔨 𝔭𝔩𝔢𝔞𝔰𝔢!"
);
assert_eq!(
nested_message.get_html_body(0).unwrap().to_string(),
"<html><body>ℌ𝔢𝔩𝔭 𝔪𝔢 𝔢𝔵𝔭𝔬𝔯𝔱 𝔪𝔶 𝔟𝔬𝔬𝔨 𝔭𝔩𝔢𝔞𝔰𝔢!</body></html>"
);

let nested_attachment = match nested_message.get_attachment(0).unwrap() {
MessagePart::Binary(v) => v,
_ => unreachable!(),
};

assert_eq!(nested_attachment.len(), 42);

// Full RFC2231 support for continuations and character sets
assert_eq!(
nested_attachment
.get_header()
.unwrap()
.get_content_type()
.unwrap()
.get_attribute("name")
.unwrap(),
"Book about ☕ tables.gif"
);

// Integrates with Serde
println!("{}", serde_json::to_string_pretty(&message).unwrap());
println!("{}", serde_yaml::to_string(&message).unwrap());

The mail-parser library is available on Crates.io (https://crates.io/crates/mail-parser) and the documentation at https://docs.rs/mail-parser/.

Please follow us on Twitter for updates!