[−][src]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 aMail
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 theContent-Type header or
Domain`).mail-smtp
bindings tonew-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 theFrom
/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 inFrom
/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 tohandlebars
. This feature is re-exported in the crate as thehandlebars
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 theheader_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; |
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 |
error | Module containing all custom errors produced by this crate. |
error | re-export of all error types |
header_components | This modules contains all components provided by this library. |
header_encoding | This module provides the encoding buffer. |
header_map | Module containing the |
headers | |
mime | Module containing some utilities for MIME usage/creation. |
utils | Utilities. |
Macros
def_headers | Defines a new header types with given type name, filed name and component |
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 | |
an email of the form | |
EncData |
|
EncodableMail | a mail with all contained futures resolved, so that it can be encoded |
Header | |
HeaderMap | A header map is a collection representing a number of mail headers in an specific order. |
HeaderName | Note: Normally you will never have the need to create a HeaderName instance by
yourself (except maybe for testing). At last as long as you use |
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). |
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. |
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 | |
HasHeaderName | a utility trait allowing us to use type hint structs
in |
HeaderKind | Trait representing a mail header. |
HeaderObjTrait | |
HeaderObjTraitBoxExt | |
HeaderTryFrom | Workaround for |
HeaderTryInto | Workaround for |
MaxOneMarker |
Type Definitions
HeaderObj | Type alias for HeaderObjTrait's trait object. |