Swoosh v0.21.0 Swoosh.Email View Source
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@example.com"}
to
- the email address for the recipient(s), example:[{"Steve Rogers", "steve.rogers@example.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@example.com"}]
bcc
- the intended blind carbon copy recipient(s) of the email, example:[{"Janet Pym", "wasp.avengers@example.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@example.com"}
headers
- a map of headers that should be included in the email, example:%{"X-Accept-Language" => "en-us, en"}
attachments
- a list of attachments that should be included in the email, example:[%{path: "/data/uuid-random", filename: "att.zip", content_type: "application/zip"}]
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"}
hackney_options
will be passed to underlining hackney post call
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@example.com")
|> from("bruce.banner@example.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@example.com"})
|> cc("wasp.avengers@example.com")
|> bcc(["thor.odinson@example.com", {"Henry McCoy", "beast.avengers@example.com"}])
|> html_body("<h1>Special Welcome</h1>")
You can also directly pass arguments to the new/1
function.
email = new(from: "tony.stark@example.com", to: "steve.rogers@example.com", subject: "Hello, Avengers!")
Link to this section Summary
Functions
Stores a new variable key and value in the email
Add a new attachment 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
Link to this section Types
address()
View Source
address() :: String.t()
address() :: String.t()
html_body()
View Source
html_body() :: String.t()
html_body() :: String.t()
mailbox() View Source
name()
View Source
name() :: String.t()
name() :: String.t()
subject()
View Source
subject() :: String.t()
subject() :: String.t()
t()
View Source
t() :: %Swoosh.Email{
assigns: map(),
attachments: [Swoosh.Attachment.t()],
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()]
}
t() :: %Swoosh.Email{ assigns: map(), attachments: [Swoosh.Attachment.t()], 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()] }
text_body()
View Source
text_body() :: String.t()
text_body() :: String.t()
Link to this section Functions
assign(email, key, value) View Source
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: [], bcc: [],
cc: [], from: nil, headers: %{}, html_body: nil, private: %{},
provider_options: %{}, reply_to: nil, subject: "", text_body: nil, to: []}
attachment(email, path)
View Source
attachment(t(), binary() | Swoosh.Attachment.t()) :: t()
attachment(t(), binary() | Swoosh.Attachment.t()) :: t()
Add a new attachment in the email.
You can pass the path to a file, a Swoosh.Attachment
or a %Plug.Upload{}
struct
as an argument. If you give a path we will detect the MIME type and determine the filename
automatically.
You can also send an inline-attachment used for embedding images in the body of emails by specifying type: :inline
Examples
iex> new() |> attachment("/data/att.zip")
%Swoosh.Email{assigns: %{}, bcc: [], cc: [], from: nil,
headers: %{}, html_body: nil, private: %{}, provider_options: %{},
reply_to: nil, subject: "", text_body: nil, to: [],
attachments: [%Swoosh.Attachment{path: "/data/att.zip",
content_type: "application/zip", filename: "att.zip",
type: :attachment, data: nil, headers: []}]}
iex> new() |> attachment(Swoosh.Attachment.new("/data/att.zip"))
%Swoosh.Email{assigns: %{}, bcc: [], cc: [], from: nil,
headers: %{}, html_body: nil, private: %{}, provider_options: %{},
reply_to: nil, subject: "", text_body: nil, to: [],
attachments: [%Swoosh.Attachment{path: "/data/att.zip",
content_type: "application/zip", filename: "att.zip",
type: :attachment, data: nil, headers: []}]}
iex> new() |> attachment(%Plug.Upload{path: "/data/abcdefg", content_type: "test/type", filename: "att.zip"})
%Swoosh.Email{assigns: %{}, bcc: [], cc: [], from: nil,
headers: %{}, html_body: nil, private: %{}, provider_options: %{},
reply_to: nil, subject: "", text_body: nil, to: [],
attachments: [%Swoosh.Attachment{path: "/data/abcdefg",
content_type: "test/type", filename: "att.zip",
type: :attachment, data: nil, headers: []}]}
iex> new() |> attachment(Swoosh.Attachment.new("/data/att.png", type: :inline))
%Swoosh.Email{assigns: %{}, bcc: [], cc: [], from: nil,
headers: %{}, html_body: nil, private: %{}, provider_options: %{},
reply_to: nil, subject: "", text_body: nil, to: [],
attachments: [%Swoosh.Attachment{path: "/data/att.png",
content_type: "image/png", filename: "att.png",
type: :inline, data: nil, headers: []}]}
bcc(email, recipients) View Source
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@example.com")
%Swoosh.Email{assigns: %{}, attachments: [], bcc: [{"", "steve.rogers@example.com"}],
cc: [], from: nil, headers: %{}, html_body: nil,
private: %{}, provider_options: %{}, reply_to: nil, subject: "",
text_body: nil, to: []}
cc(email, recipients) View Source
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@example.com")
%Swoosh.Email{assigns: %{}, attachments: [], bcc: [],
cc: [{"", "steve.rogers@example.com"}], from: nil, headers: %{}, html_body: nil,
private: %{}, provider_options: %{}, reply_to: nil, subject: "",
text_body: nil, to: []}
from(email, from) View Source
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@example.com"})
%Swoosh.Email{assigns: %{}, attachments: [], bcc: [], cc: [], from: {"Steve Rogers", "steve.rogers@example.com"},
headers: %{}, html_body: nil, private: %{}, provider_options: %{},
reply_to: nil, subject: "", text_body: nil, to: []}
iex> new() |> from("steve.rogers@example.com")
%Swoosh.Email{assigns: %{}, attachments: [], bcc: [], cc: [], from: {"", "steve.rogers@example.com"},
headers: %{}, html_body: nil, private: %{}, provider_options: %{},
reply_to: nil, subject: "", text_body: nil, to: []}
header(email, name, value) View Source
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: [], 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) View Source
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: [], bcc: [],
cc: [], from: nil, headers: %{}, html_body: "<h1>Hello</h1>",
private: %{}, provider_options: %{}, reply_to: nil, subject: "",
text_body: nil, to: []}
new(opts \\ []) View Source
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@example.com")
%Swoosh.Email{from: {"", "tony.stark@example.com"}}
iex> new(from: {"Tony Stark", "tony.stark@example.com"})
%Swoosh.Email{from: {"Tony Stark", "tony.stark@example.com"}}
iex> new(to: "steve.rogers@example.com")
%Swoosh.Email{to: [{"", "steve.rogers@example.com"}]}
iex> new(to: {"Steve Rogers", "steve.rogers@example.com"})
%Swoosh.Email{to: [{"Steve Rogers", "steve.rogers@example.com"}]}
iex> new(to: [{"Bruce Banner", "bruce.banner@example.com"}, "thor.odinson@example.com"])
%Swoosh.Email{to: [{"Bruce Banner", "bruce.banner@example.com"}, {"", "thor.odinson@example.com"}]}
iex> new(cc: "steve.rogers@example.com")
%Swoosh.Email{cc: [{"", "steve.rogers@example.com"}]}
iex> new(cc: {"Steve Rogers", "steve.rogers@example.com"})
%Swoosh.Email{cc: [{"Steve Rogers", "steve.rogers@example.com"}]}
iex> new(cc: [{"Bruce Banner", "bruce.banner@example.com"}, "thor.odinson@example.com"])
%Swoosh.Email{cc: [{"Bruce Banner", "bruce.banner@example.com"}, {"", "thor.odinson@example.com"}]}
iex> new(bcc: "steve.rogers@example.com")
%Swoosh.Email{bcc: [{"", "steve.rogers@example.com"}]}
iex> new(bcc: {"Steve Rogers", "steve.rogers@example.com"})
%Swoosh.Email{bcc: [{"Steve Rogers", "steve.rogers@example.com"}]}
iex> new(bcc: [{"Bruce Banner", "bruce.banner@example.com"}, "thor.odinson@example.com"])
%Swoosh.Email{bcc: [{"Bruce Banner", "bruce.banner@example.com"}, {"", "thor.odinson@example.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@example.com")
%Swoosh.Email{reply_to: {"", "edwin.jarvis@example.com"}}
iex> new(reply_to: {"Edwin Jarvis", "edwin.jarvis@example.com"})
%Swoosh.Email{reply_to: {"Edwin Jarvis", "edwin.jarvis@example.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@example.com", subject: "Hello, Avengers!")
%Swoosh.Email{to: [{"", "steve.rogers@example.com"}], subject: "Hello, Avengers!"}
put_bcc(email, recipients) View Source
Puts new recipients in the bcc
field.
It will replace any previously added bcc
recipients.
put_cc(email, recipients) View Source
Puts new recipients in the cc
field.
It will replace any previously added cc
recipients.
put_private(email, key, value) View Source
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: [], 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) View Source
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: [], 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) View Source
Puts new recipients in the to
field.
It will replace any previously added to
recipients.
reply_to(email, reply_to) View Source
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@example.com"})
%Swoosh.Email{assigns: %{}, attachments: [], bcc: [], cc: [], from: nil,
headers: %{}, html_body: nil, private: %{}, provider_options: %{},
reply_to: {"Steve Rogers", "steve.rogers@example.com"}, subject: "", text_body: nil, to: []}
iex> new() |> reply_to("steve.rogers@example.com")
%Swoosh.Email{assigns: %{}, attachments: [], bcc: [], cc: [], from: nil,
headers: %{}, html_body: nil, private: %{}, provider_options: %{},
reply_to: {"", "steve.rogers@example.com"}, subject: "", text_body: nil, to: []}
subject(email, subject) View Source
Sets the subject
field.
The subject must be a string that contains the subject.
Examples
iex> new() |> subject("Hello, Avengers!")
%Swoosh.Email{assigns: %{}, attachments: [], 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) View Source
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: [], bcc: [],
cc: [], from: nil, headers: %{}, html_body: nil,
private: %{}, provider_options: %{}, reply_to: nil, subject: "",
text_body: "Hello", to: []}
to(email, recipients) View Source
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@example.com")
%Swoosh.Email{assigns: %{}, attachments: [], bcc: [],
cc: [], from: nil, headers: %{}, html_body: nil,
private: %{}, provider_options: %{}, reply_to: nil, subject: "",
text_body: nil, to: [{"", "steve.rogers@example.com"}]}