mail / mail-api
Documentation can be viewed on docs.rs. (at least once it's published ;=) )
Facade which re-exports functionality from a number of mail related crates.
The crates include:
mail-internals
some parts used by more or less all othermail-*
crates likeMailType
, some grammar parts or theEncodingBuffer
. Asmail-internals
is mainly used internally it's not directly exposed.mail-headers
functionality wrt. mail (mime) header, including a HeaderMap containing the header fields (keeping insertion order) a number of components used in header field bodies like e.g.Mailbox
orPhrase
and default implementations for many headers, including From, To, Sender, Data, Subject, Date, MessageId, Cc, Bcc, etc.mail-core
provides the typeMail
which represents a (possible) multi-part mime Mail and includes functionality for encoding it. It also contains an abstraction for the content of multi-part mails calledResource
, which includes support for embeddings, attachments etc.mail-template
provides functionality to create aMail
from a template, including multi-part mails containing embeddings and attachments. It's not bound to a specific template engine. Currently bindings for the tera template engine are provided behind feature flag.mail-smtp
(feature:smtp
) provides bindings betweenmail-core
andnew-tokio-smtp
allowing the simple sending of mails to a specific server. It's mainly focused on the use-case where mails are sent to an Mail Submission Agent (MSA) which then distributes themmail-render-template-engine
(featurerender-template-engine
) provides a partial implementation for theTemplateEngine
trait frommail-template
only missing a "render engine" to render the template. The implementation includes functionality for automatically generating multiple alternate bodies (e.g. text, html) embedding, and attachments based on a spec, which can be derived and loaded from a folder/file layout making it easy to create and maintain complex mail templates.
Examples
mail_by_hand
Creates and encodes a simple mail without using any fancy helpers, templates or similar.
mail_from_template
Uses the bindings for the tera
template engine to create a mail, including
alternate bodies and an attachment.
send_mail
A simple program which queries the user for information and then sends a (simple) mail to an MSA (Mail Submission Agent). While it is currently limited to STARTTLS on port 587, Auth Plain and only simple text mails this is a limitation of this cli program not the mail libraries which can handle other forms of connecting and authenticating etc.
Note that this is meant to send data to an MSA NOT a MX (Mail Exchanger), e.g.
smtp.gmail.com
is a MSA but gmail-smtp-in.l.google.com
is an MX. Also note
that some mail providers do not accept Auth Plain (at least not without
enabling it in the security settings). The reason for this is that they prefer
that applications do not use username+password for authentication but other
formats e.g. OAuth2 tokens.
Rest assured that the authentication data is only sent over a TLS encrypted
channel. Still if you don't trust it consider using some throw away or testing
mail service e.g. ethereal.email
.
Lastly the examples uses the same unique seed every time, which means that
Message-ID's, and Content-ID's are not guaranteed to be world unique even
through they should (again a limitation of the example not the mail crate).
Nevertheless given that it also doesn't use its "own" domain but a .test
domain it can't guarantee world uniqueness anyway.
Features
smtp
Provides bindings to new-tokio-smtp
under mail::smtp
by reexporting the
mail-smtp
crate
render-template-engine
Provides the render template engine under mail::render_template_engine
.
askama-engine
Provides bindings to the askama
crate (a template engine) under
mail::askama
tera-engine
Provides bindings to the tera
crate (a template engine) under mail::tera
.
This feature uses the render-template-engine
feature.
traceing
Enables the traceing
debugging functionality in the EncodingBuffer
from mail-internals
, this is only used for testing header implementations
and comes with noticeable overhead. As such this should not be enabled
except for testing header implementations. Also EncodingBuffer
isn't
re-exported as it can be seen as an internal part of the implementation
which normally doesn't need to be accessed directly.
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.