1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
//! This crate provides a general interface for using template engine with the mail crate.
//!
//! It's core is the `TemplateEngine` trait which can be implemented to bind a template engine.
//! When rendering a template the template engine implementing the `TemplateEngine` trait will
//! produce a number of (wrapped) `Resource` instances representing the alternate bodies of a mail as well
//! as a number of additional `Resources` used for embedded content (e.g. logo images) and
//! attachments. This crate then takes this parts and composes a multipart mime mail from
//! it.
//!
//! # Template Engine implementations
//!
//! A mail template engine has to do more then just taking a single text
//! template (e.g. a handlebars template) and produce some output using
//! string magic. It has to:
//!
//! 1. consider alternate bodies, so it should render at last two
//! "text templates" (one text/plain, one html)
//! 2. consider which additional embeddings/attachments should be included
//! (all in the given template data are included, but you might
//! add additional ones, e.g. some logo image)
//!
//! As such text template engines like `Handle` bar can not directly
//! be bound to the `TemplateEngine` trait.
//!
//! For using text template engine it's recommended to use
//! the `mail-template-render-engine` (also exposed through the
//! mail facade) which implements this overhead for any engine
//! which can "just" render some text and provides default
//! bindings to some common template engines (e.g. Handlebars).
//!
//! # Derive
//!
//! This crate requires template data to implement `InspectEmbeddedResources`
//! which combined with some typing/generic design decisions allows to bind
//! not just to template engines which use serialization to access template
//! data but also to such which use static typing (like `askama`).
//!
//! As such it re-exports the `InspectEmbeddedResources` derive from
//! `mail-derive`. Note that if you use the mail facade it also does
//! re-export the derive.
//!
//! # Features
//!
//! - `askama-engine`, includes bindings for the askama template engine.
//! - `serialize-to-content-id`, implements Serialize for `Embedded`,
//! `EmbeddedWithCId` which serializes the embedded type **into its
//! content id**. E.g. a image with content id `"q09cu3@example.com"`
//! will be serialized to the string `"q09cu3@example.com"`. This is
//! extremely useful for all template engines which use serialization
//! as their way to access template data.
//!
//!
//! # Example
//!
//! ```
//!
//! ```
//!
//! # Road Map
//!
//! The current implementation has a number of limitations which should be lifted with
//! future versions:
//!
//! - Only a limited subset of headers are/can be set through the template engine
//! (`Sender`, `From`, `To`, `Subject`) while some headers are set implicitly
//! when encoding the mail (e.g. `Date`, `Content-Type`, `Content-Disposition`).
//! But sometimes it would be useful to add some custom headers through the template
//! engine (both on the outermost and inner bodies).
//!
//! - `From`, `To`, `Subject` have to be given, but sometimes you might want to just
//! create the `Mail` type and then set them by yourself (through you _can_ currently
//! override them)
//!
//! - Re-use/integration of existing mail instances: Some times you might want to
//! use a `Mail` instance created some where else as a body for a multipart mail
//! generated from a template (e.g. some thing generating "special" attachments).
//!
//!
//! Also there are some parts which are likely to change:
//!
//! - `MailSendData`/`MailSendDataBuilder` the name is
//! not very good it also needs to change to handle
//! the thinks listed above
//!
//! - `Embedded`, `EmbeddedWithCid`, embeddings and attachments
//! currently a `Embedded` instance is a wrapper around `Resource`
//! representing something which will become a mail body but is not
//! a main body (i.e. it not the text/html/.. you send) instead it
//! something embedded in the mail which is either used as attachment
//! or as a embedding (e.g. a logo image). Through the content disposition
//! the `Embedded` instance differs between thing embedded and internally
//! used or embedded and used as attachment at the same time many different
//! arrays are sometimes used to differ between them (e.g. in `MailParts`)
//! but there is no (type system) check to make sure a array of thinks used
//! as attachments can not contain a `Embedded` instance with content disposition
//! inline. The result will still be a valid mail, but likely not in the
//! way you expect it to be. This should be fixed one way or another (making
//! the different array type safe and lifting disposition to the type level
//! had been used but didn't play out nicely).
//!
//! - `serialize-to-content-id`, is a nice idea but has some problems in
//! some edge cases (e.g. when you want to serialize anything containing
//! a `Embedded` type for any usage BUT accessing it in an template). So
//! it might be removed, which means a import like `cid:{{data.mything}}`
//! (using some mustach pseudo template syntax) would become `cid:{{data.mything.cid}}`.
//!
extern crate mail_types as mail;
extern crate mail_common as common;
#[macro_use]
extern crate mail_headers as headers;
#[macro_use]
extern crate failure;
extern crate mime as media_type;
extern crate futures;
extern crate soft_ascii_string;
#[macro_use]
extern crate vec1;
#[cfg(feature="serialize-to-content-id")]
extern crate serde;
#[cfg(feature="askama-engine")]
#[cfg_attr(test, macro_use)]
extern crate askama;
#[macro_use]
#[allow(unused_imports)]
extern crate mail_derive;
//re-export proc-macro
pub use mail_derive::*;
//modules are ordered in "after-can-import-from-before" order
pub mod error;
mod resource;
mod template_engine;
mod builder_extension;
mod compositor;
#[cfg(feature="askama-engine")]
pub mod askama_engine;
// re-exports flatten crate
pub use self::builder_extension::*;
pub use self::compositor::*;
pub use self::resource::*;
pub use self::template_engine::*;
|
