diff options
| author | Kartikaya Gupta <kgupta@mozilla.com> | 2016-06-18 17:44:17 +0100 |
|---|---|---|
| committer | Kartikaya Gupta <kgupta@mozilla.com> | 2016-06-18 17:44:17 +0100 |
| commit | 9483b5dfee71375900bf2fae37b9c240b09b73a2 (patch) | |
| tree | 2cda539a5060380cea491b0de9716e89cab6bdaf /README.md | |
| parent | 5a022e8422cbfdd2ccbd27e672a26796e19cf4c9 (diff) | |
Add some crate metadata
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 58 |
1 files changed, 58 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..36fd249 --- /dev/null +++ b/README.md @@ -0,0 +1,58 @@ +mailparse +=== + +A simple parser for MIME email messages. + +API +--- +The primary entry point for this library is the following function: + +```rust + parse_mail(&[u8]) -> Result<ParsedMail, MailParseError> +``` + +This function takes the raw message data, including headers and body, and returns a structured object to more easily access pieces of the email message. +There are other public functions that allow parsing smaller parts of the message as well; refer to the [full documentation](http://staktrace.github.io/mailparse/target/doc/mailparse/). + +The library is designed to process real-world email data such as might be obtained by using the FETCH command on an IMAP server. +As such, this library should successfully handle any valid MIME-formatted message, although it may not follow all the strict requirements in the various specifications that cover the format (predominantly IETF RFC 822 and IETF RFC 2045). +As an example, this library accepts raw message data which uses \n (ASCII LF) as line delimiters rather than the RFC-mandated \r\n (ASCII CRLF) line delimiters. + +Example usage +--- + +```rust + use mailparse::*; + let parsed = parse_mail(concat!( + "Subject: This is a test email\n", + "Content-Type: multipart/alternative; boundary=foobar\n", + "\n", + "--foobar\n", + "Content-Type: text/plain; charset=utf-8\n", + "Content-Transfer-Encoding: quoted-printable\n", + "\n", + "This is the plaintext version, in utf-8. Proof by Euro: =E2=82=AC\n", + "--foobar\n", + "Content-Type: text/html\n", + "Content-Transfer-Encoding: base64\n", + "\n", + "PGh0bWw+PGJvZHk+VGhpcyBpcyB0aGUgPGI+SFRNTDwvYj4gdmVyc2lvbiwgaW4g \n", + "dXMtYXNjaWkuIFByb29mIGJ5IEV1cm86ICZldXJvOzwvYm9keT48L2h0bWw+Cg== \n", + "--foobar--\n", + "After the final boundary stuff gets ignored.\n").as_bytes()) + .unwrap(); + assert_eq!(parsed.headers.get_first_value("Subject").unwrap(), Some("This is a test email".to_string())); + assert_eq!(parsed.subparts.len(), 2); + assert_eq!(parsed.subparts[0].get_body().unwrap(), "This is the plaintext version, in utf-8. Proof by Euro: \u{20AC}"); + assert_eq!(parsed.subparts[1].headers[1].get_value().unwrap(), "base64"); + assert_eq!(parsed.subparts[1].ctype.mimetype, "text/html"); + assert!(parsed.subparts[1].get_body().unwrap().starts_with("<html>")); +``` + +Documentation +--- +See the rustdoc at [http://staktrace.github.io/mailparse/target/doc/mailparse/](http://staktrace.github.io/mailparse/target/doc/mailparse/). + +Other notes +--- +This is written by a newbie Rust programmer, so code may be non-idiomatic or suboptimal. Pull requests are welcome! |