ex_postmark v1.3.0 ExPostmark.Email

Defines an Email.

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

Email fields

subject - the subject of the email, example: "Hello, Avengers!"
from - an email address of the sender, example: {"Tony Stark", "tony.stark@example.com"}
to - an email address for the recipient(s), example: [{"Steve Rogers", "steve.rogers@example.com"}]
cc - an intended carbon copy recipient(s) of the email, example: [{"Bruce Banner", "hulk.smash@example.com"}]
bcc - an intended blind carbon copy recipient(s) of the email, example: [{"Janet Pym", "wasp.avengers@example.com"}]
reply_to - an 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"}
template_id - a template to use when sending this message, example: 97854
template_model - a model to be applied to the specified template to generate HtmlBody, TextBody, and Subject, example: %{team: "Avengers"}

Examples

email =
  new
  |> to("tony.stark@example.com")
  |> from("bruce.banner@example.com")
  |> template_id(97854)
  |> template_model(%{team: 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"}])

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!")

Summary

Types

address()

mailbox()

name()

subject()

t()

Functions

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

new(opts \\ [])

Returns a ExPostmark.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_headers(email, name, value)

Adds a new header in the email

put_template_model(email, key, value)

Stores a new template_model 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

template_id(email, template_id)

Sets the template_id field

to(email, recipients)

Adds new recipients in the to field

Types

address()

address() :: String.t

mailbox()

mailbox() :: {name, address}

name()

name() :: String.t

subject()

subject() :: String.t

t()

t() :: %ExPostmark.Email{bcc: [mailbox] | [], cc: [mailbox] | [], from: mailbox | nil, headers: map, reply_to: mailbox | nil, subject: subject, template_id: pos_integer, template_model: map, to: [mailbox]}

Functions

bcc(email, recipients)

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@example.com")
%ExPostmark.Email{bcc: [{"", "steve.rogers@example.com"}], cc: [],
 from: nil, headers: %{}, reply_to: nil,
 template_id: nil, template_model: nil, to: []}

cc(email, recipients)

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@example.com")
%ExPostmark.Email{bcc: [], cc: [{"", "steve.rogers@example.com"}],
 from: nil, headers: %{}, reply_to: nil,
 template_id: nil, template_model: nil, to: []}

from(email, from)

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@example.com"})
%ExPostmark.Email{bcc: [], cc: [],
 from: {"Steve Rogers", "steve.rogers@example.com"}, headers: %{},
 reply_to: nil, template_id: nil,
 template_model: nil, to: []}

iex> new |> from("steve.rogers@example.com")
%ExPostmark.Email{bcc: [], cc: [],
 from: {"", "steve.rogers@example.com"}, headers: %{},
 reply_to: nil, template_id: nil, template_model: nil,
 to: []}

new(opts \\ [])

new(none | Enum.t) :: t

Returns a ExPostmark.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
%ExPostmark.Email{}

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

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

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

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

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

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

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

iex> new(template_id: 1)
%ExPostmark.Email{template_id: 1}

iex> new(template_model: %{team: "Avengers"})
%ExPostmark.Email{template_model: %{team: "Avengers"}}

You can obviously combine these arguments together:

iex> new(to: "steve.rogers@example.com", template_id: 1, subject: "Hello, Avengers!")
%ExPostmark.Email{to: [{"", "steve.rogers@example.com"}], template_id: 1, subject: "Hello, Avengers!"}

put_bcc(email, recipients)

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)

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

Puts new recipients in the cc field.

It will replace any previously added cc recipients.

put_headers(email, name, value)

put_headers(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 |> put_headers("X-Magic-Number", "7")
%ExPostmark.Email{bcc: [], cc: [], from: nil,
 headers: %{"X-Magic-Number" => "7"}, reply_to: nil,
 template_id: nil, template_model: nil, to: []}

put_template_model(email, key, value)

put_template_model(t, atom, any) :: t

Stores a new template_model 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_template_model(:team, "Avengers")
%ExPostmark.Email{bcc: [], cc: [], from: nil, headers: %{},
 reply_to: nil, template_id: nil,
 template_model: %{team: "Avengers"}, to: []}

put_to(email, recipients)

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)

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@example.com"})
%ExPostmark.Email{bcc: [], cc: [], from: nil, headers: %{},
 reply_to: {"Steve Rogers", "steve.rogers@example.com"},
 template_id: nil, template_model: nil, to: []}

iex> new |> reply_to("steve.rogers@example.com")
%ExPostmark.Email{bcc: [], cc: [], from: nil, headers: %{},
 reply_to: {"", "steve.rogers@example.com"},
 template_id: nil, template_model: nil, to: []}

subject(email, subject)

subject(t, subject) :: t

Sets the subject field.

The subject must be a string that contains the subject.

Examples

iex> new |> subject("Hello, Avengers!")
%ExPostmark.Email{bcc: [], cc: [],
 from: nil, headers: %{},
 reply_to: nil, template_id: nil, template_model: {subject: "Hello, Avengers!"},
 template_model: nil, to: []}

template_id(email, template_id)

template_id(t, pos_integer) :: t

Sets the template_id field.

The template ID must be a positive integer that corresponds to the template ID defined in admin panel.

Examples

iex> new |> template_id(1)
%ExPostmark.Email{bcc: [], cc: [], from: nil, headers: %{},
 reply_to: nil, template_id: 1,
 template_model: nil, to: []}

to(email, recipients)

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@example.com")
%ExPostmark.Email{bcc: [], cc: [], from: nil, headers: %{},
 reply_to: nil, template_id: nil,
 template_model: nil, to: [{"", "steve.rogers@example.com"}]}