mail_smtp/
lib.rs

1//! This library binds together `new-tokio-smtp` and the `mail` crates.
2//!
3//! It can be used to send mail given  as mail crates `Mail` instances
4//! to a Mail Submission Agent (MSA). It could, theoretically also
5//! be used to send to an MX, but this often needs additional functionality
6//! for reliable usage which is not part of this crate.
7//!
8//! For ease of use this crate re-exports some of the most commonly used
9//! parts from `new-tokio-smtp` including `ConnectionConfig`,
10//! `ConnectionBuilder`, all authentication commands/methods (the
11//! `auth` module) as well as useful types (in the `misc` module).
12//!
13//! The `send_mails` function is the simplest way to send a batch
14//! of mails. Nevertheless it doesn't directly accept `Mail` instances,
15//! instead it accepts `MailRequest` instances. This is needed, as
16//! the sender/recipient(s) specified through the `Mail` headers
17//! and those used fro smtp mail delivery are not necessary exactly
18//! the same (e.g. for bounce back mails and some no-reply setups).
19//!
20//! # Example
21//!
22//! ```no_run
23//! extern crate futures;
24//! //if you use the mail facade use the re-exports from it instead
25//! extern crate mail_core;
26//! extern crate mail_smtp;
27//! #[macro_use] extern crate mail_headers;
28//!
29//! use futures::Future;
30//! use mail_headers::{
31//!     headers::*,
32//!     header_components::Domain
33//! };
34//! use mail_core::{Mail, default_impl::simple_context};
35//! use mail_smtp::{self as smtp, ConnectionConfig};
36//!
37//! # fn main() {
38//! // this is normally done _once per application instance_
39//! // and then stored in e.g. a lazy_static. Also `Domain`
40//! // will implement `FromStr` in the future.
41//! let ctx = simple_context::new(Domain::from_unchecked("example.com".to_owned()), "asdkds".parse().unwrap())
42//!     .unwrap();
43//!
44//! let mut mail = Mail::plain_text("Some body", &ctx);
45//! mail.insert_headers(headers! {
46//!     _From: ["bla@example.com"],
47//!     _To: ["blub@example.com"],
48//!     Subject: "Some Mail"
49//! }.unwrap());
50//!
51//! // don't use unencrypted con for anything but testing and
52//! // simplified examples
53//! let con_config = ConnectionConfig::builder_local_unencrypted().build();
54//!
55//! let fut = smtp::send(mail.into(), con_config, ctx);
56//! let results = fut.wait();
57//! # }
58//! ```
59//!
60//!
61extern crate futures;
62extern crate new_tokio_smtp;
63extern crate mail_core as mail;
64extern crate mail_internals;
65#[cfg_attr(test, macro_use)]
66extern crate mail_headers as headers;
67#[macro_use]
68extern crate failure;
69
70mod resolve_all;
71
72pub mod error;
73mod request;
74mod send_mail;
75
76pub use self::request::MailRequest;
77#[cfg(feature="extended-api")]
78pub use self::request::derive_envelop_data_from_mail;
79
80pub use self::send_mail::{send, send_batch};
81#[cfg(feature="extended-api")]
82pub use self::send_mail::encode;
83
84pub use new_tokio_smtp::{ConnectionConfig, ConnectionBuilder};
85
86pub mod auth {
87    //! Module containing authentification commands/methods.
88    //!
89    //! This Module is re-exported from `new-tokio-smtp` for
90    //! ease of use.
91
92    pub use new_tokio_smtp::command::auth::*;
93
94    /// Auth command for not doing anything on auth.
95    //FIXME: this currently still sends the noop cmd,
96    // replace it with some new "NoCommand" command.
97    pub type NoAuth = ::new_tokio_smtp::command::Noop;
98}
99
100pub mod misc {
101    //! A small collection of usefull types re-exported from `new-tokio-smtp`.
102    pub use new_tokio_smtp::{
103        ClientId,
104        Domain,
105        AddressLiteral,
106        SetupTls,
107        DefaultTlsSetup,
108        Cmd
109    };
110}
mail_smtp/lib.rs

mail_smtp/
lib.rs
