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

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. (once published)

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (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.