1 files changed, 65 insertions, 0 deletions
diff --git a/README.md b/README.md
index f148293..485865e 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,71 @@ Take a look at the [`mail-api` crate](https://github.com/1aim/mail-api) for more
 
 Documentation can be [viewed on docs.rs](https://docs.rs/mail-smtp).
 
+## Example
+
+This library binds together `new-tokio-smtp` and the `mail` crates.
+
+It can be used to send mail given  as mail crates `Mail` instances
+to a Mail Submission Agent (MSA). It could, theoretically also
+be used to send to an MX, but this often needs additional functionality
+for reliable usage which is not part of this crate.
+
+For ease of use this crate re-exports some of the most commonly used
+parts from `new-tokio-smtp` including `ConnectionConfig`,
+`ConnectionBuilder`, all authentication commands/methods (the
+`auth` module) as well as useful types (in the `misc` module).
+
+The `send_mails` function is the simplest way to send a batch
+of mails. Nevertheless it doesn't directly accept `Mail` instances,
+instead it accepts `MailRequest` instances. This is needed, as
+the sender/recipient(s) specified through the `Mail` headers
+and those used fro smtp mail delivery are not necessary exactly
+the same (e.g. for bounce back mails and some no-reply setups).
+
+# Example
+
+```rust ,no_run
+extern crate futures;
+//if you use the mail facade use the re-exports from it instead
+extern crate mail_types;
+extern crate mail_smtp;
+#[macro_use] extern crate mail_headers;
+
+use futures::Future;
+use mail_headers::*;
+use mail_headers::components::Domain;
+use mail_types::{Mail, default_impl::simple_context};
+use mail_smtp::{send_mails, ConnectionConfig};
+
+fn main() {
+    // this is normally done _once per application instance_
+    // and then stored in e.g. a lazy_static. Also `Domain`
+    // will implement `FromStr` in the future.
+    let ctx = simple_context::new(
+        Domain::from_unchecked("example.com".to_owned(),
+        // This should be "world" unique for the given domain
+        // to assure message and content ids are world unique.
+        "asdkds".parse().unwrap()
+    ).unwrap();
+
+    let mut mail = Mail::plain_text("Some body").unwrap();
+    mail.set_headers(headers! {
+        _From: ["bla@example.com"],
+        _To: ["blub@example.com"],
+        Subject: "Some Mail"
+    }.unwrap()).unwrap();
+
+    // don't use unencrypted con for anything but testing and
+    // simplified examples
+    let con_config = ConnectionConfig::build_local_unencrypted().build();
+
+    let fut = send_mails(con_config, vec![mail.into()], ctx);
+    let results = fut.wait();
+}
+```
+
+
+
 ## License
 
 Licensed under either of