diff options
author | Philipp Korber <p.korber@1aim.com> | 2018-11-16 16:15:42 +0100 |
---|---|---|
committer | Philipp Korber <p.korber@1aim.com> | 2018-11-16 16:15:42 +0100 |
commit | caf049791b8e7107734cd1f8917d51c91a2b80ad (patch) | |
tree | 338b7edede2a3df91e6712f0567bce61a705fc66 /smtp/README.md | |
parent | bad94a94285a6d13cb02c26702c525a9e1b3e32f (diff) |
refactor: prepared to be merged into different repository
Diffstat (limited to 'smtp/README.md')
-rw-r--r-- | smtp/README.md | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/smtp/README.md b/smtp/README.md new file mode 100644 index 0000000..b02fade --- /dev/null +++ b/smtp/README.md @@ -0,0 +1,88 @@ +# mail-smtp   + +**Allows sending `mail-core` `Mail`'s through `new-tokio-smtp`** + +--- + + +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_core; +extern crate mail_smtp; +#[macro_use] extern crate mail_headers; + +use futures::Future; +use mail_headers::*; +use mail_headers::components::Domain; +use mail_core::{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(); +} +``` + + +## Documentation + +Documentation can be [viewed on docs.rs](https://docs.rs/mail-smtp). +(once published) + +## License + +Licensed under either of + +* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) +* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) + +at your option. + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any +additional terms or conditions. |