Swoosh v0.4.0 Swoosh.Email

Defines an Email.

This module defines a Swoosh.Email struct and the main functions for composing an email. As it is the contract for the public APIs of Swoosh it is a good idea to make use of these functions rather than build the struct yourself.

Email fields

  • from - the email address of the sender, example: {"Tony Stark", "tony@stark.com"}
  • to - the email address for the recipient(s), example: [{"Steve Rogers", "steve@rogers.com"}]
  • subject - the subject of the email, example: "Hello, Avengers!"
  • cc - the intended carbon copy recipient(s) of the email, example: [{"Bruce Banner", "hulk@smash.com"}]
  • bcc - the intended blind carbon copy recipient(s) of the email, example: [{"Janet Pym", "wasp@avengers.com"}]
  • text_body - the content of the email in plaintext, example: "Hello"
  • html_body - the content of the email in HTML, example: "<h1>Hello</h1>"
  • reply_to - the email address that should receive replies, example: {"Clints Barton", "hawk@eye.com"}
  • headers - a map of headers that should be included in the email, example: %{"X-Accept-Language" => "en-us, en"}
  • assigns - a map of values that correspond with any template variables, example: %{"first_name" => "Bruce"}

Private

This key is reserved for use with adapters, libraries and frameworks.

  • private - a map of values that are for use by libraries/frameworks, example: %{phoenix_template: "welcome.html.eex"}

Provider options

This key allow users to make use of provider-specific functionality by passing along addition parameters.

  • provider_options - a map of values that are specific to adapter provider, example: %{async: true}

Examples

email =
  new
  |> to("tony@stark.com")
  |> from("bruce@banner.com")
  |> text_body("Welcome to the Avengers")

The composable nature makes it very easy to continue expanding upon a given Email.

email =
  email
  |> cc({"Steve Rogers", "steve@rogers.com"})
  |> cc("wasp@avengers.com")
  |> bcc(["thor@odinson.com", {"Henry McCoy", "beast@avengers.com"}])
  |> html_body("<h1>Special Welcome</h1>")

You can also directly pass arguments to the new/1 function.

email = new(from: "tony@stark.com", to: "steve@rogers.com", subject: "Hello, Avengers!")

Summary

Functions

Stores a new variable key and value in the email

Adds new recipients in the bcc field

Adds new recipients in the cc field

Sets a recipient in the from field

Adds a new header in the email

Sets the html_body field

Returns a Swoosh.Email struct

Puts new recipients in the bcc field

Puts new recipients in the cc field

Stores a new private key and value in the email

Stores a new provider_option key and value in the email

Puts new recipients in the to field

Sets a recipient in the reply_to field

Sets the subject field

Sets the text_body field

Adds new recipients in the to field

Types

t :: %Swoosh.Email{assigns: map, attachments: term, bcc: [mailbox] | [], cc: [mailbox] | [], from: mailbox | nil, headers: map, html_body: html_body | nil, private: map, provider_options: map, reply_to: mailbox | nil, subject: String.t, text_body: text_body | nil, to: [mailbox]}

Functions

assign(email, key, value)

Specs

assign(t, atom, any) :: t

Stores a new variable key and value in the email.

This store is meant for variables used in templating. The name should be specified as an atom, the value can be any term.

Examples

iex> new |> assign(:username, "ironman")
%Swoosh.Email{assigns: %{username: "ironman"}, attachments: nil, bcc: [],
 cc: [], from: nil, headers: %{}, html_body: nil, private: %{},
 provider_options: %{}, reply_to: nil, subject: "", text_body: nil, to: []}
bcc(email, recipients)

Specs

bcc(t, mailbox | address | [mailbox | address]) :: t

Adds new recipients in the bcc field.

The recipient must be; a tuple specifying the name and address of the recipient; a string specifying the address of the recipient; or an array comprised of a combination of either.

iex> new |> bcc("steve@rogers.com")
%Swoosh.Email{assigns: %{}, attachments: nil, bcc: [{"", "steve@rogers.com"}],
 cc: [], from: nil, headers: %{}, html_body: nil,
 private: %{}, provider_options: %{}, reply_to: nil, subject: "",
 text_body: nil, to: []}
cc(email, recipients)

Specs

cc(t, mailbox | address | [mailbox | address]) :: t

Adds new recipients in the cc field.

The recipient must be; a tuple specifying the name and address of the recipient; a string specifying the address of the recipient; or an array comprised of a combination of either.

Examples

iex> new |> cc("steve@rogers.com")
%Swoosh.Email{assigns: %{}, attachments: nil, bcc: [],
 cc: [{"", "steve@rogers.com"}], from: nil, headers: %{}, html_body: nil,
 private: %{}, provider_options: %{}, reply_to: nil, subject: "",
 text_body: nil, to: []}
from(email, from)

Specs

from(t, mailbox | address) :: t

Sets a recipient in the from field.

The recipient must be either; a tuple specifying the name and address of the recipient; a string specifying the address of the recipient.

Examples

iex> new |> from({"Steve Rogers", "steve@rogers.com"})
%Swoosh.Email{assigns: %{}, attachments: nil, bcc: [], cc: [], from: {"Steve Rogers", "steve@rogers.com"},
 headers: %{}, html_body: nil, private: %{}, provider_options: %{},
 reply_to: nil, subject: "", text_body: nil, to: []}

iex> new |> from("steve@rogers.com")
%Swoosh.Email{assigns: %{}, attachments: nil, bcc: [], cc: [], from: {"", "steve@rogers.com"},
 headers: %{}, html_body: nil, private: %{}, provider_options: %{},
 reply_to: nil, subject: "", text_body: nil, to: []}
header(email, name, value)

Specs

header(t, String.t, String.t) :: t

Adds a new header in the email.

The name and value must be specified as strings.

Examples

iex> new |> header("X-Magic-Number", "7")
%Swoosh.Email{assigns: %{}, attachments: nil, bcc: [], cc: [], from: nil,
 headers: %{"X-Magic-Number" => "7"}, html_body: nil, private: %{},
 provider_options: %{}, reply_to: nil, subject: "", text_body: nil, to: []}
html_body(email, html_body)

Specs

html_body(t, html_body | nil) :: t

Sets the html_body field.

The HTML body must be a string that containing the HTML content.

Examples

iex> new |> html_body("<h1>Hello</h1>")
%Swoosh.Email{assigns: %{}, attachments: nil, bcc: [],
 cc: [], from: nil, headers: %{}, html_body: "<h1>Hello</h1>",
 private: %{}, provider_options: %{}, reply_to: nil, subject: "",
 text_body: nil, to: []}
new(opts \\ [])

Specs

new(none | Enum.t) :: t

Returns a Swoosh.Email struct.

You can pass a keyword list or a map argument to the function that will be used to populate the fields of that struct. Note that it will silently ignore any fields that it doesn’t know about.

Examples

iex> new
%Swoosh.Email{}

iex> new(subject: "Hello, Avengers!")
%Swoosh.Email{subject: "Hello, Avengers!"}

iex> new(from: "tony@stark.com")
%Swoosh.Email{from: {"", "tony@stark.com"}}
iex> new(from: {"Tony Stark", "tony@stark.com"})
%Swoosh.Email{from: {"Tony Stark", "tony@stark.com"}}

iex> new(to: "steve@rogers.com")
%Swoosh.Email{to: [{"", "steve@rogers.com"}]}
iex> new(to: {"Steve Rogers", "steve@rogers.com"})
%Swoosh.Email{to: [{"Steve Rogers", "steve@rogers.com"}]}
iex> new(to: [{"Bruce Banner", "bruce@banner.com"}, "thor@odinson.com"])
%Swoosh.Email{to: [{"Bruce Banner", "bruce@banner.com"}, {"", "thor@odinson.com"}]}

iex> new(cc: "steve@rogers.com")
%Swoosh.Email{cc: [{"", "steve@rogers.com"}]}
iex> new(cc: {"Steve Rogers", "steve@rogers.com"})
%Swoosh.Email{cc: [{"Steve Rogers", "steve@rogers.com"}]}
iex> new(cc: [{"Bruce Banner", "bruce@banner.com"}, "thor@odinson.com"])
%Swoosh.Email{cc: [{"Bruce Banner", "bruce@banner.com"}, {"", "thor@odinson.com"}]}

iex> new(bcc: "steve@rogers.com")
%Swoosh.Email{bcc: [{"", "steve@rogers.com"}]}
iex> new(bcc: {"Steve Rogers", "steve@rogers.com"})
%Swoosh.Email{bcc: [{"Steve Rogers", "steve@rogers.com"}]}
iex> new(bcc: [{"Bruce Banner", "bruce@banner.com"}, "thor@odinson.com"])
%Swoosh.Email{bcc: [{"Bruce Banner", "bruce@banner.com"}, {"", "thor@odinson.com"}]}

iex> new(html_body: "<h1>Welcome, Avengers</h1>")
%Swoosh.Email{html_body: "<h1>Welcome, Avengers</h1>"}

iex> new(text_body: "Welcome, Avengers")
%Swoosh.Email{text_body: "Welcome, Avengers"}

iex> new(reply_to: "edwin@jarvis.com")
%Swoosh.Email{reply_to: {"", "edwin@jarvis.com"}}
iex> new(reply_to: {"Edwin Jarvis", "edwin@jarvis.com"})
%Swoosh.Email{reply_to: {"Edwin Jarvis", "edwin@jarvis.com"}}

iex> new(headers: %{"X-Accept-Language" => "en"})
%Swoosh.Email{headers: %{"X-Accept-Language" => "en"}}

iex> new(assigns: %{user_id: 10})
%Swoosh.Email{assigns: %{user_id: 10}}

iex> new(provider_options: %{async: true})
%Swoosh.Email{provider_options: %{async: true}}

You can obviously combine these arguments together:

iex> new(to: "steve@rogers.com", subject: "Hello, Avengers!")
%Swoosh.Email{to: [{"", "steve@rogers.com"}], subject: "Hello, Avengers!"}
put_bcc(email, recipients)

Specs

put_bcc(t, mailbox | address | [mailbox | address]) :: t

Puts new recipients in the bcc field.

It will replace any previously added bcc recipients.

put_cc(email, recipients)

Specs

put_cc(t, mailbox | address | [mailbox | address]) :: t

Puts new recipients in the cc field.

It will replace any previously added cc recipients.

put_private(email, key, value)

Specs

put_private(t, atom, any) :: t

Stores a new private key and value in the email.

This store is meant to be for libraries/framework usage. The name should be specified as an atom, the value can be any term.

Examples

iex> new |> put_private(:phoenix_template, "welcome.html")
%Swoosh.Email{assigns: %{}, attachments: nil, bcc: [], cc: [], from: nil,
 headers: %{}, html_body: nil, private: %{phoenix_template: "welcome.html"},
 provider_options: %{}, reply_to: nil, subject: "", text_body: nil, to: []}
put_provider_option(email, key, value)

Specs

put_provider_option(t, atom, any) :: t

Stores a new provider_option key and value in the email.

This store is meant for adapter usage, to aid provider-specific functionality. The name should be specified as an atom, the value can be any term.

Examples

iex> new |> put_provider_option(:async, true)
%Swoosh.Email{assigns: %{}, attachments: nil, bcc: [], cc: [], from: nil,
 headers: %{}, html_body: nil, private: %{}, provider_options: %{async: true},
 reply_to: nil, subject: "", text_body: nil, to: []}
put_to(email, recipients)

Specs

put_to(t, mailbox | address | [mailbox | address]) :: t

Puts new recipients in the to field.

It will replace any previously added to recipients.

reply_to(email, reply_to)

Specs

reply_to(t, mailbox | address) :: t

Sets a recipient in the reply_to field.

The recipient must be either; a tuple specifying the name and address of the recipient; a string specifying the address of the recipient.

Examples

iex> new |> reply_to({"Steve Rogers", "steve@rogers.com"})
%Swoosh.Email{assigns: %{}, attachments: nil, bcc: [], cc: [], from: nil,
 headers: %{}, html_body: nil, private: %{}, provider_options: %{},
 reply_to: {"Steve Rogers", "steve@rogers.com"}, subject: "", text_body: nil, to: []}

iex> new |> reply_to("steve@rogers.com")
%Swoosh.Email{assigns: %{}, attachments: nil, bcc: [], cc: [], from: nil,
 headers: %{}, html_body: nil, private: %{}, provider_options: %{},
 reply_to: {"", "steve@rogers.com"}, subject: "", text_body: nil, to: []}
subject(email, subject)

Specs

subject(t, subject) :: t

Sets the subject field.

The subject must be a string that contains the subject.

Examples

iex> new |> subject("Hello, Avengers!")
%Swoosh.Email{assigns: %{}, attachments: nil, bcc: [],
 cc: [], from: nil, headers: %{}, html_body: nil,
 private: %{}, provider_options: %{}, reply_to: nil, subject: "Hello, Avengers!",
 text_body: nil, to: []}
text_body(email, text_body)

Specs

text_body(t, text_body | nil) :: t

Sets the text_body field.

The text body must be a string that containing the plaintext content.

Examples

iex> new |> text_body("Hello")
%Swoosh.Email{assigns: %{}, attachments: nil, bcc: [],
 cc: [], from: nil, headers: %{}, html_body: nil,
 private: %{}, provider_options: %{}, reply_to: nil, subject: "",
 text_body: "Hello", to: []}
to(email, recipients)

Specs

to(t, mailbox | address | [mailbox | address]) :: t

Adds new recipients in the to field.

The recipient must be; a tuple specifying the name and address of the recipient; a string specifying the address of the recipient; or an array comprised of a combination of either.

Examples

iex> new |> to("steve@rogers.com")
%Swoosh.Email{assigns: %{}, attachments: nil, bcc: [],
 cc: [], from: nil, headers: %{}, html_body: nil,
 private: %{}, provider_options: %{}, reply_to: nil, subject: "",
 text_body: nil, to: [{"", "steve@rogers.com"}]}