diff options
| -rw-r--r-- | Cargo.toml | 7 | ||||
| -rw-r--r-- | LICENSE | 5 | ||||
| -rw-r--r-- | README.md | 58 |
3 files changed, 70 insertions, 0 deletions
@@ -2,6 +2,13 @@ name = "mailparse" version = "0.1.0" authors = ["Kartikaya Gupta <kats@seldon.staktrace.com>"] +description = "A simple parser for MIME e-mail messages" +documentation = "https://staktrace.github.io/mailparse/target/doc/mailparse/" +homepage = "https://github.com/staktrace/mailparse/blob/master/README.md" +repository = "https://github.com/staktrace/mailparse" +readme = "README.md" +keywords = ["parser", "email", "mail", "rfc822", "mime"] +license-file = "LICENSE" [dependencies] base64 = "0.1.1" @@ -0,0 +1,5 @@ +Copyright (C) 2016 by Kartikaya Gupta. + +Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 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! |