diff options
Diffstat (limited to 'src/lib.rs')
-rw-r--r-- | src/lib.rs | 58 |
1 files changed, 58 insertions, 0 deletions
@@ -1,3 +1,61 @@ +//! 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 +//! +//! ```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()), "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(); +//! # } +//! ``` +//! +//! extern crate futures; extern crate new_tokio_smtp; extern crate mail_types as mail; |