Swoosh
v1.10.1

View Source Swoosh.Email (Swoosh v1.10.1)

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

 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: {"Clint 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

 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"}
    • client_options will be passed to underlining http client post call

provider-options

 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

 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

Types

address()
html_body()
mailbox()
name()
subject()
t()
text_body()

Functions

assign(email, key, value)

Stores a new variable key and value in the email.

attachment(email, path)

Add a new attachment in the email.

bcc(email, recipients)

Adds new recipients in the bcc field.

cc(email, recipients)

Adds new recipients in the cc field.

from(email, from)

Sets a recipient in the from field.

header(email, name, value)

Adds a new header in the email.

html_body(email, html_body)

Sets the html_body field.

new(opts \\ [])

Returns a Swoosh.Email struct.

put_bcc(email, recipients)

Puts new recipients in the bcc field.

put_cc(email, recipients)

Puts new recipients in the cc field.

put_private(email, key, value)

Stores a new private key and value in the email.

put_provider_option(email, key, value)

Stores a new provider_option key and value in the email.

put_to(email, recipients)

Puts new recipients in the to field.

reply_to(email, reply_to)

Sets a recipient in the reply_to field.

subject(email, subject)

Sets the subject field.

text_body(email, text_body)

Sets the text_body field.

to(email, recipients)

Adds new recipients in the to field.

Link to this section Types

Link to this type

address()

View Source 
@type address() :: String.t()
Link to this type

html_body()

View Source 
@type html_body() :: String.t()
Link to this type

mailbox()

View Source 
@type mailbox() :: {name(), address()}
Link to this type

name()

View Source 
@type name() :: String.t()
Link to this type

subject()

View Source 
@type subject() :: String.t()
Link to this type

t()

View Source 
@type 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()]
}
Link to this type

text_body()

View Source 
@type text_body() :: String.t()

Link to this section Functions

Link to this function

assign(email, key, value)

View Source 
@spec 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

 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: []}
Link to this function

attachment(email, path)

View Source 
@spec 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

 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: [], cid: nil}]}
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: [], cid: nil}]}
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: [], cid: nil}]}
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: [], cid: "att.png"}]}
Link to this function

bcc(email, recipients)

View Source 
@spec bcc(t(), Swoosh.Email.Recipient.t() | [Swoosh.Email.Recipient.t()]) :: t()

Adds new recipients in the bcc field.

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: []}
Link to this function

cc(email, recipients)

View Source 
@spec cc(t(), Swoosh.Email.Recipient.t() | [Swoosh.Email.Recipient.t()]) :: t()

Adds new recipients in the cc field.

examples

 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: []}
Link to this function

from(email, from)

View Source 
@spec from(t(), Swoosh.Email.Recipient.t()) :: t()

Sets a recipient in the from field.

examples

 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: []}
Link to this function

header(email, name, value)

View Source 
@spec header(t(), String.t(), String.t()) :: t()

Adds a new header in the email.

The name and value must be specified as strings.

examples

 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: []}
Link to this function

html_body(email, html_body)

View Source 
@spec 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

 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: []}
Link to this function

new(opts \\ [])

View Source 
@spec 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

 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!"}
Link to this function

put_bcc(email, recipients)

View Source 
@spec put_bcc(t(), Swoosh.Email.Recipient.t() | [Swoosh.Email.Recipient.t()]) :: t()

Puts new recipients in the bcc field.

It will replace any previously added bcc recipients.

Link to this function

put_cc(email, recipients)

View Source 
@spec put_cc(t(), Swoosh.Email.Recipient.t() | [Swoosh.Email.Recipient.t()]) :: t()

Puts new recipients in the cc field.

It will replace any previously added cc recipients.

Link to this function

put_private(email, key, value)

View Source 
@spec 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

 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: []}
Link to this function

put_provider_option(email, key, value)

View Source 
@spec 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

 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: []}
Link to this function

put_to(email, recipients)

View Source 
@spec put_to(t(), Swoosh.Email.Recipient.t() | [Swoosh.Email.Recipient.t()]) :: t()

Puts new recipients in the to field.

It will replace any previously added to recipients.

Link to this function

reply_to(email, reply_to)

View Source 
@spec reply_to(t(), Swoosh.Email.Recipient.t()) :: t()

Sets a recipient in the reply_to field.

examples

 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: []}
Link to this function

subject(email, subject)

View Source 
@spec subject(t(), subject()) :: t()

Sets the subject field.

The subject must be a string that contains the subject.

examples

 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: []}
Link to this function

text_body(email, text_body)

View Source 
@spec 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

 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: []}
Link to this function

to(email, recipients)

View Source 
@spec to(t(), Swoosh.Email.Recipient.t() | [Swoosh.Email.Recipient.t()]) :: t()

Adds new recipients in the to field.

examples

 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"}]}