Crate mail

Facade which re-exports functionality from a number of mail related crates.

The facade should re-export enough functionality for using the mail carate to create/modify/encode mail, send them over smtp (feature) or use a handlebars based template engine to create them from a template (feature).

Functionality steming from following crates is re-exported:

• mail-core provides a Mail type and the core functionality around creating/modifing/encoding mails.
• mail-headers provides implementations for the headers of the mail. This also includes a number of header components which appear in mail header bodies but are also re-used in other placed (e.g. MediaType stemming from the Content-Type header or Domain`).
• mail-smtp bindings to new-tokio-smtp to make it easier to send mails over smtp. This also includes functionality to automatically derive the smtp sender/receiver from the mail if no sender/receiver is explicitly given (Smtp by it's standard does not use the From/To headers of a mail. Instead it treats the mail, including it's headers mostly as a opaque block of data. But in practice the addresses in From/To/Sender tend to match the smtp sender/recipient).
• mail-template provides a simple way to bind template engine to generate mails. It has a feature which if enable directly includes bindings to handlebars. This feature is re-exported in the crate as the handlebars feature.
• mail-internals provides some shared mostly internal parts the other crates use. This is normally only needed if you write your own mail header implementations. But even then the does this crate re-expost the parts most likely needed (in the header_encoding module).

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 handlebars 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 and would fail many spam filters, so if you use it make sure to change this to the right values for your use case.

Features

smtp

Provides bindings to new-tokio-smtp under mail::smtp by reexporting the mail-smtp crate

handlebars

Provides a mail-template engine implementation using the handlebars crate. It can be found under mail::template::handlebars::Handlebars;

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.

Re-exports

pub extern crate mail_template as template;

pub extern crate mail_smtp as smtp;

Modules

compose	This module provides utilities for composing multipart mails.
context	Provides the context needed for building/encoding mails.
default_impl	This module provides an number of default implementations for some of the interfaces.
default_impl	Re-export of the default_impl parts from mail-core.
error	Module containing all custom errors produced by this crate.
error	re-export of all error types
header_components	Re-export of headers from mail-headers. This modules contains all components provided by this library.
header_encoding	This module provides the encoding buffer.
header_map	Re-export of headers from mail-headers. Module containing the HeaderMap.
headers	Re-export of headers from mail-headers.
mime	Module containing some utilities for MIME usage/creation.
utils	Utilities.

Macros

def_headers	Re-export of headers from mail-headers. Defines a new header types with given type name, filed name and component
headers	Re-export of headers from mail-headers. Create a header map from a list of header's with ther fields

Structs

Data	A type containing some data and metadata for it.
Domain
Email	an email of the form local-part@domain corresponds to RFC5322 addr-spec, so <, > padding is not part of this Email type (but of the Mailbox type instead)
EncData	EncData is like Data but the buffer contains transfer encoded data.
EncodableMail	a mail with all contained futures resolved, so that it can be encoded
Header	Re-export of headers from mail-headers.
HeaderMap	Re-export of headers from mail-headers. A header map is a collection representing a number of mail headers in an specific order.
HeaderName	Re-export of headers from mail-headers.
IRI	A minimal IRI (International Resource Identifier) implementation which just parses the scheme but no scheme specific part (and neither fragments wrt. those definitions in which fragments are not scheme specific parts).
Mail	A type representing a Mail.
MailFuture	A future resolving to an encodable mail.
Mailbox
MediaType
Metadata	POD type containing FileMeta, Content-Type and Content-Id
ResourceContainerLoadingFuture
Source	POD containing the IRI which should be used to laod a resource well as an optional file name to use and a description about how the content type should be handled.

Enums

MailBody	A type which either represents a single body, or multiple modies.
MailType	Specifies what kind of mail we want to create.
MaybeEncData	Represents Data which might already have been transfer encoded.
Resource	A enum specifying a "resource" for a mail.
TransferEncodingHint	Hint to change how data should be transfer encoded.
UseMediaType	Specifies how the content type should be handled when loading the data.

Traits

ContainedResourcesAccess
Context	This library needs a context for creating/encoding mails.
HasHeaderName	Re-export of headers from mail-headers. a utility trait allowing us to use type hint structs in HeaderMap::{contains, get_untyped}
HeaderKind	Re-export of headers from mail-headers. Trait representing a mail header.
HeaderObjTrait	Re-export of headers from mail-headers.
HeaderObjTraitBoxExt	Re-export of headers from mail-headers.
HeaderTryFrom	Re-export of headers from mail-headers. Workaround for TryFrom,TryInto not being stable.
HeaderTryInto	Re-export of headers from mail-headers. Workaround for TryFrom,TryInto not being stable.
MaxOneMarker	Re-export of headers from mail-headers.

Type Definitions

HeaderObj

Re-export of headers from mail-headers. Type alias for HeaderObjTrait's trait object.