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.
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:
consider alternate bodies, so it should render at last two "text templates" (one text/plain, one html)
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).
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.
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.rust
The current implementation has a number of limitations which should be lifted with future versions:
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)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 aboveEmbedded, 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 can be viewed on docs.rs. (once published)
Licensed under either of
at your option.
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.