diff options
author | Philipp Korber <p.korber@1aim.com> | 2018-09-06 18:35:00 +0200 |
---|---|---|
committer | Philipp Korber <p.korber@1aim.com> | 2018-09-06 18:35:00 +0200 |
commit | f02c8db8b96d2ca143f8a8c7e24961cd5dfcea47 (patch) | |
tree | 7278c56975dda8382bc2e3f142b324e132bb4697 | |
parent | 708a5454bb3579ba94a922b94e1e21d177db4ff2 (diff) |
doc(send_mail) documented new api
-rw-r--r-- | src/send_mail.rs | 43 |
1 files changed, 42 insertions, 1 deletions
diff --git a/src/send_mail.rs b/src/send_mail.rs index 861159e..6646e13 100644 --- a/src/send_mail.rs +++ b/src/send_mail.rs @@ -27,6 +27,17 @@ use ::{ request::MailRequest }; +/// Sends a given mail (request). +/// +/// - This will use the given context to encode the mail. +/// - Then it will use the connection config to open a connection to a mail +/// server (likely a Mail Submission Agent (MSA)). +/// - Following this it will send the mail to the server. +/// - After which it will close the connection again. +/// +/// You can use `MailRequest: From<Mail>` (i.e. `mail.into()`) to pass in +/// a mail and derive the envelop data (from, to) from it or create your own +/// mail request if different smtp envelop data is needed. pub fn send<A, S>(mail: MailRequest, conconf: ConnectionConfig<A, S>, ctx: impl Context) -> impl Future<Item=(), Error=MailSendError> where A: Cmd, S: SetupTls @@ -40,6 +51,26 @@ pub fn send<A, S>(mail: MailRequest, conconf: ConnectionConfig<A, S>, ctx: impl fut } +/// Sends a batch of mails to a server. +/// +/// - This will use the given context to encode all mails. +/// - After which it will use the connection config to open a connection +/// to the server (like a Mail Submission Agent (MSA)). +/// - Then it will start sending mails. +/// - If a mail fails because of an error code but setting up the connection +/// (which includes auth) didn't fail then others mails in the input will +/// still be send +/// - If the connection is broken because setting it up failed or it was +/// interrupted, then the mail at which place it was noticed will return +/// the given error and all later mails will return a I/0-Error with the +/// `ErrorKind::NoConnection` +/// - It will return a `Stream` which when polled will send the mails +/// and return results _in the order the mails had been supplied_. So +/// for each mail there will be exactly one result. +/// - Once the stream is completed the connection will automatically be +/// closed (even if the stream is not yet dropped, it closes it the +/// moment it notices that there are no more mails to send!) +/// pub fn send_batch<A, S, C>( mails: Vec<MailRequest>, conconf: ConnectionConfig<A, S>, @@ -63,7 +94,17 @@ fn collect_res<S, E>(stream: S) -> impl Future<Item=Vec<Result<S::Item, S::Error stream.then(|res| Ok(res)).collect() } - +/// Turns a `MailRequest` into a future resolving to a `MailEnvelop`. +/// +/// This function is mainly used internally for `send`, `send_batch` +/// but can be used by other libraries when `send`/`send_batch` doesn't +/// quite match their use case. E.g. if they want to have a connection +/// pool and instead of `connect->send->quit` want to have something like +/// `take_from_pool->test->send->place_back_to_pool`, in which case they +/// probably would want to do something along the lines of using encode +/// then take a connection, test it, use the mail envelops with `new-tokio-smtp`'s +/// `SendAllMails` stream with a `on_completion` handler which places it +/// back in the pool. pub fn encode<C>(request: MailRequest, ctx: C) -> impl Future<Item=MailEnvelop, Error=MailSendError> where C: Context |