diff options
| -rw-r--r-- | README.md | 17 | ||||
| -rw-r--r-- | src/error.rs | 16 | ||||
| -rw-r--r-- | src/lib.rs | 22 | ||||
| -rw-r--r-- | src/request.rs | 10 |
4 files changed, 51 insertions, 14 deletions
@@ -1,18 +1,9 @@ # mail-smtp   -_[internal/mail-api] combines the `mail-types` crate with `new-tokio-smtp` crate_ +**Allows sending `mail-types` `Mail`'s through `new-tokio-smtp`** -Mainly provides a `send_mails` method, which given a `ConnectionConfig` and -an iterable source of `MailRequest`'s (e.g. `Vec<MailRequest>`) sends all mails -to the server specified in the `ConnectionConfig`. This includes setting up -the connection running an auth command, encoding all mails, sending each mail -and closing the connection afterwards. +--- -Take a look at the [`mail-api` crate](https://github.com/1aim/mail-api) for more details. - -Documentation can be [viewed on docs.rs](https://docs.rs/mail-smtp). - -## Example This library binds together `new-tokio-smtp` and the `mail` crates. @@ -76,6 +67,10 @@ fn main() { ``` +## Documentation + +Documentation can be [viewed on docs.rs](https://docs.rs/mail-smtp). +(once published) ## License diff --git a/src/error.rs b/src/error.rs index 24cccf1..850e0ee 100644 --- a/src/error.rs +++ b/src/error.rs @@ -1,9 +1,15 @@ +//! Module containing all custom errors. use std::{io as std_io}; use new_tokio_smtp::error::{ConnectingFailed, LogicError}; use mail::error::MailError; +/// Error used when sending a mail fails. +/// +/// Failing to encode a mail before sending +/// it also counts as a `MailSendError`, as +/// it's done "on the fly" when sending a mail. #[derive(Debug, Fail)] pub enum MailSendError { /// Creating the mail failed. @@ -41,6 +47,16 @@ impl From<LogicError> for MailSendError { } } +/// Error returned when something on the transport layer failed. +/// +/// Thinks causing this error include: +/// +/// - TLS required but not supported by server +/// - authentication not valid +/// - connection "broke" (e.g. because you +/// internet connection is gone or the server +/// crashed) +/// #[derive(Debug, Fail)] pub enum TransportError { /// Setting up the connection failed. @@ -74,14 +74,32 @@ pub use self::request::MailRequest; #[cfg(feature="extended-api")] pub use self::request::derive_envelop_data_from_mail; -pub use self::send_mail::{send_mails, SendMailResult}; +pub use self::send_mail::{ + send_mails, + SendMailResult +}; #[cfg(feature="extended-api")] pub use self::send_mail::{encode_mails, send_encoded_mails}; pub use new_tokio_smtp::{ConnectionConfig, ConnectionBuilder}; -pub use new_tokio_smtp::command::auth; + +pub mod auth { + //! Module containing authentification commands/methods. + //! + //! This Module is re-exported from `new-tokio-smtp` for + //! ease of use. + + pub use new_tokio_smtp::command::auth::*; + + /// Auth command for not doing anything on auth. + //FIXME: this currently still sends the noop cmd, + // replace it with some new "NoCommand" command. + pub type NoAuth = ::new_tokio_smtp::command::Noop; +} + pub mod misc { + //! A small collection of usefull types re-exported from `new-tokio-smtp`. pub use new_tokio_smtp::ClientId; pub use new_tokio_smtp::Domain; pub use new_tokio_smtp::AddressLiteral; diff --git a/src/request.rs b/src/request.rs index b5689d6..b6191f6 100644 --- a/src/request.rs +++ b/src/request.rs @@ -15,7 +15,15 @@ use headers::error::BuildInValidationError; use mail::Mail; use mail::error::MailError; - +/// This type contains a mail and potentially some envelop data. +/// +/// It is needed as in some edge cases the smtp envelop data (i.e. +/// smtp from and smtp recipient) can not be correctly derived +/// from the mail. +/// +/// The default usage is to directly turn a `Mail` into a `MailRequest` +/// by either using `MailRequest::new`, `MailRequest::from` or `Mail::into`. +/// #[derive(Clone, Debug)] pub struct MailRequest { mail: Mail, |