[][src]Struct mail_core::Mail

pub struct Mail { /* fields omitted */ }

A type representing a Mail.

This type is used to represent a mail including headers and body. It is also used for the bodies of multipart mime mail bodies as they can be seen as "sub-mails" or "hirachical nested mails", at last wrt. everything relevant on this type.

A mail can be created using the Builder or more specific either the SinglepartBuilder or the MultipartBuilder for a multipart mime mail.

Example

This will create, encode and print a simple plain text mail.

use std::str;
// either from `mail::headers` or from `mail_header as headers`
use headers::{
    headers::*,
    header_components::Domain
};
use mail_core::{
    Mail, Resource,
    default_impl::simple_context
};

// Domain will implement `from_str` in the future,
// currently it doesn't have a validator/parser.
let domain = Domain::from_unchecked("example.com".to_owned());
// Normally you create this _once per application_.
let ctx = simple_context::new(domain, "xqi93".parse().unwrap())
    .unwrap();

let mut mail = Mail::plain_text("Hy there!", &ctx);
mail.insert_headers(headers! {
    _From: [("I'm Awesome", "bla@examle.com")],
    _To: ["unknow@example.com"],
    Subject: "Hy there message"
}.unwrap());

// We don't added anythink which needs loading but we could have
// and all of it would have been loaded concurrent and async.
let encoded = mail.into_encodable_mail(ctx.clone())
    .wait().unwrap()
    .encode_into_bytes(MailType::Ascii).unwrap();

let mail_str = str::from_utf8(&encoded).unwrap();
println!("{}", mail_str);

And here is an example to create the same mail using the builder:

// either from `mail::headers` or from `mail_header as headers`
use headers::{
    headers::*,
};
use mail_core::{Mail,  Resource};

let resource = Resource::plain_text("Hy there!", &ctx);
let mut mail = Mail::new_singlepart_mail(resource);
mail.insert_headers(headers! {
    _From: [("I'm Awesome", "bla@examle.com")],
    _To: ["unknow@example.com"],
    Subject: "Hy there message"
}.unwrap());

And here is an example creating a multipart mail with a made up multipart type.

// either from `mail::headers` or from `mail_header as headers`
use headers::{
    headers::*,
    header_components::{
        MediaType,
    }
};
use mail_core::{Mail, Resource};

let sub_body1 = Mail::plain_text("Body 1", &ctx);
let sub_body2 = Mail::plain_text("Body 2, yay", &ctx);

// This will generate `multipart/x.made-up-think; boundary=randome_generate_boundary`
let media_type = MediaType::new("multipart", "x.made-up-thing").unwrap();
let mut mail = Mail::new_multipart_mail(media_type, vec![sub_body1, sub_body2]);
mail.insert_headers(headers! {
    _From: [("I'm Awesome", "bla@examle.com")],
    _To: ["unknow@example.com"],
    Subject: "Hy there message"
}.unwrap());

Methods

impl Mail
[src]

Create a new plain text mail.

This will

  • turn the text into a String
  • generate a new ContentId using the context
  • create a Resource from the String (with content type text/plain; charset=utf-8)
  • create a mail from the resource

Returns true if the body of the mail is a multipart body.

Create a new multipart mail with given content type and given bodies.

Note that while the given content_type has to be a multipart content type (when encoding the mail) it is not required nor expected to have the boundary parameter. The boundary will always be automatically generated independently of wether or not it was passed as media type.

Create a new non-multipart mail for given Resource as body.

Inserts a new header into the header map.

This will call insert on the inner HeaderMap, which means all behavior of HeaderMap::insert does apply, like e.g. the "max one" behavior.

Inserts all headers into the inner header map.

This will call HeaderMap::insert_all internally which means all behavior of HeaderMap::insert does apply, like e.g. the "max one" behavior.

Returns a reference to the currently set headers.

Note that some headers namely Content-Transfer-Encoding as well as Content-Type for singlepart mails are derived from the content and should not be set. If done so they are either ignored or an error is caused by them in other parts of the crate (like e.g. encoding). Also Date is auto-generated if not set and it is needed.

Return a mutable reference to the currently set headers.

Returns a reference to the body/bodies.

Return a mutable reference to the body/bodies.

Validate the mail.

This will mainly validate the mail headers by

  • checking if no ContentTransferHeader is given
  • (for mails with multipart bodies) checking if the content type is a multipart media type
  • (for mail with non-multipart bodies) check if there is no content type header (as the content type header will be derived from he Resource)
  • running all header validators (with use_contextual_validators) this also checks for "max one" consistency (see HeaderMap's documentation for more details)
  • doing this recursively with all contained mails

Note that this will be called by into_encodable_mail, therefor it is normally not required to call this function by yourself.

Be aware that this does a general validation applicable to both the top level headers and headers from multipart mail sub bodies. This means it e.g. doesn't check if there are any of the required headers (Date and From).

Turns the mail into a future with resolves to an EncodableMail.

While this future resolves it will do following thinks:

  1. Validate the mail.

    • This uses generally_validate_mail.
    • Additionally it does check for required top level headers which will not be auto-generated (the From header).
  2. Make sure all resources are loaded and transfer encoded.

    • This will concurrently load + transfer encode all resources replacing the old resource instances with the new loaded and encoded ones once all of them had been loaded (and encoded) successfully.
  3. Insert all auto generated headers (like e.g. Date).

  4. Insert boundary parameters into all multipart media types (overriding any existing one).

Use this if you want to encode a mail. This is needed as Resource instances used in the mail are loaded "on-demand", i.e. if you attach two images but never turn the mail into an encodable mail the images are never loaded from disk.

impl Mail
[src]

Create a multipart/mixed Mail instance containing this mail as first body and one additional body for each attachment.

Normally this is used with embeddings having a attachment disposition creating a mail with attachments.

Create a multipart/alternative Mail instance containing this mail as the main body with given alternatives.

The "priority" of alternative bodies is ascending with the body which should be shown only if all other bodies can't be displayed first. I.e. the order is the same order as specified by multipart/alternative. This also means that this body will be the last body as it is meant to be the main body.

Creates a multipart/related Mail instance containing this mail first and then all related bodies.

Trait Implementations

impl Clone for Mail
[src]

Performs copy-assignment from source. Read more

impl Into<Mail> for EncodableMail
[src]

impl Debug for Mail
[src]

Auto Trait Implementations

impl Send for Mail

impl Sync for Mail

Blanket Implementations

impl<T> From for T
[src]

impl<T, U> Into for T where
    U: From<T>, 
[src]

impl<T> ToOwned for T where
    T: Clone
[src]

impl<T, U> TryFrom for T where
    T: From<U>, 
[src]

🔬 This is a nightly-only experimental API. (try_from)

The type returned in the event of a conversion error.

impl<T> Borrow for T where
    T: ?Sized
[src]

impl<T> BorrowMut for T where
    T: ?Sized
[src]

impl<T, U> TryInto for T where
    U: TryFrom<T>, 
[src]

🔬 This is a nightly-only experimental API. (try_from)

The type returned in the event of a conversion error.

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<F, T> HeaderTryInto for F where
    T: HeaderTryFrom<F>, 
[src]

impl<T> HeaderTryFrom for T
[src]

impl<T> Erased for T