Bamboo.Email (bamboo v2.0.0) View Source
Contains functions for composing emails.
Bamboo separates composing emails from delivering them. This separation makes emails easy to test and makes things like using a default layout or a default from address easy to do. This module is for creating emails. To actually send them, use Bamboo.Mailer.
Handling email addresses
The from, to, cc, and bcc addresses of a Bamboo.Email can be set to any
data structure for which there is an implementation of the
Bamboo.Formatter protocol or a list of such data
structures. Bamboo includes implementations for some common data structures
or you can create your own. All from, to, cc, and bcc addresses are
normalized internally to a two item tuple of {name, address}. See
Bamboo.Formatter for more info.
Simplest way to create a new email
defmodule MyApp.Email do
import Bamboo.Email
def welcome_email(user) do
new_email(
from: "me@app.com",
to: user,
subject: "Welcome!",
text_body: "Welcome to the app",
html_body: "<strong>Welcome to the app</strong>"
)
end
endExtracting common parts (default layout, default from address, etc.)
Let's say you want all emails to have the same from address. Here's how you could do that
defmodule MyApp.Email do
import Bamboo.Email
def welcome_email(user) do
# Since new_email/1 returns a struct you can update it with Kernel.struct!/2
struct!(base_email(),
to: user,
subject: "Welcome!",
text_body: "Welcome to the app",
html_body: "<strong>Welcome to the app</strong>"
)
end
def base_email do
new_email(from: "me@app.com")
end
endIn addition to keyword lists, Bamboo.Emails can also be built using function pipelines.
defmodule MyApp.Email do
import Bamboo.Email
def welcome_email(user) do
base_email()
|> to(user)
|> subject("Welcome!")
|> text_body("Welcome to the app")
|> html_body("<strong>Welcome to the app</strong>")
end
endLink to this section Summary
Functions
Returns a list of all recipients (to, cc and bcc).
Sets the bcc on the email.
Sets the cc on the email.
Sets the from on the email.
Gets just the email address from a normalized email address
Sets the html_body on the email
Used to create a new email
Adds a data attachment to the email
Adds a file attachment to the email
Adds a header to the email
Adds a key/value to the private key of the email
Sets the subject on the email
Sets the text_body on the email
Sets the to on the email.
Link to this section Types
Specs
Specs
Specs
t() :: %Bamboo.Email{
assigns: %{optional(atom()) => any()},
attachments: term(),
bcc: address_list(),
cc: address_list(),
from: term(),
headers: %{optional(String.t()) => String.t()},
html_body: nil | String.t(),
private: %{optional(atom()) => any()},
subject: nil | String.t(),
text_body: nil | String.t(),
to: address_list()
}
Link to this section Functions
Specs
all_recipients(Bamboo.Email.t()) :: [address()] | no_return()
Returns a list of all recipients (to, cc and bcc).
Specs
bcc(Bamboo.Email.t(), address_list()) :: Bamboo.Email.t()
Sets the bcc on the email.
bcc receives as an argument any data structure for which
there is an implementation of the Bamboo.Formatter protocol.
new_email()
|> bcc(["sally@example.com", "james@example.com"])Specs
cc(Bamboo.Email.t(), address_list()) :: Bamboo.Email.t()
Sets the cc on the email.
cc receives as an argument any data structure for which
there is an implementation of the Bamboo.Formatter protocol.
new_email()
|> cc(["sally@example.com", "james@example.com"])Specs
from(Bamboo.Email.t(), address_list()) :: Bamboo.Email.t()
Sets the from on the email.
from receives as an argument any data structure for which
there is an implementation of the Bamboo.Formatter protocol.
new_email()
|> from(["sally@example.com", "james@example.com"])Specs
Gets just the email address from a normalized email address
Normalized email addresses are 2 item tuples {name, address}. This gets the
address part of the tuple. Use this instead of calling elem(address, 1)
so that if Bamboo changes how email addresses are represented your code will
still work
Examples
Bamboo.Email.get_address({"Paul", "paul@thoughtbot.com"}) # "paul@thoughtbot.com"Sets the html_body on the email
Specs
new_email(Enum.t()) :: Bamboo.Email.t()
Used to create a new email
If called without arguments it is the same as creating an empty
%Bamboo.Email{} struct. If called with arguments it will populate the struct
with given attributes.
Example
# Same as %Bamboo.Email{from: "support@myapp.com"}
new_email(from: "support@myapp.com")Adds a data attachment to the email
Example
put_attachment(email, %Bamboo.Attachment{})Requires the fields filename and data of the %Bamboo.Attachment{} struct to be set.
Example
def create(conn, params) do
#...
email
|> put_attachment(%Bamboo.Attachment{filename: "event.ics", data: "BEGIN:VCALENDAR..."})
#...
endAdds a file attachment to the email
Example
put_attachment(email, path, opts \\ [])Accepts filename: <name> and content_type: <type> options.
If you are using Plug, it accepts a Plug.Upload struct
Example
def create(conn, params) do
#...
email
|> put_attachment(params["file"])
#...
endSpecs
put_header(Bamboo.Email.t(), String.t(), String.t()) :: Bamboo.Email.t()
Adds a header to the email
Example
put_header(email, "Reply-To", "support@myapp.com")Specs
put_private(Bamboo.Email.t(), atom(), any()) :: Bamboo.Email.t()
Adds a key/value to the private key of the email
This is mostly used to implement specific functionality for a particular adapter. It will rarely be used directly from your code. Internally this is used to set Mandrill specific params for the MandrillAdapter and it's also used to store the view module, template and layout when using Bamboo.Phoenix.
Example
put_private(email, :tags, "welcome-email")Sets the subject on the email
Sets the text_body on the email
Specs
to(Bamboo.Email.t(), address_list()) :: Bamboo.Email.t()
Sets the to on the email.
to receives as an argument any data structure for which
there is an implementation of the Bamboo.Formatter protocol.
new_email()
|> to(["sally@example.com", "james@example.com"])