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
|
# mail-template
**Provides mechanisms for generating mails based on templates**
---
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 amail as well as a number of additional `Resources` used for embedded content (e.g. logoimages) 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
```rust
```
## 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}}`.
## Documentation
Documentation can be [viewed on docs.rs](https://docs.rs/mail-template).
(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.
|
