sendgrid

v2.0.0

sendgrid v2.0.0 SendGrid.Email View Source

Email primitive for composing emails with SendGrid’s API.

You can easily compose on an Email to set the fields of your email.

Example 

Email.build()
|> Email.add_to("test@email.com")
|> Email.put_from("test2@email.com")
|> Email.put_subject("Hello from Elixir")
|> Email.put_text("Sent with Elixir")
|> SendGrid.Mail.send()

SendGrid Specific Features

Many common features of SendGrid V3 API for transactional emails are supported.

Templates

You can use a SendGrid template by providing a template id.

put_template(email, "some_template_id")

Substitutions

You can provided a key-value pair for subsititions to have text replaced.

add_substitution(email, "-key-", "value")

Scheduled Sending

You can provide a Unix timestamp to have an email delivered in the future.

send_at(email, 1409348513)

Phoenix Views

You can use Phoenix Views to set your HTML and text content of your emails. You just have to provide a view module and template name and you’re good to go! Additionally, you can set a layout to render the view in with put_phoenix_layout/2. See put_phoenix_template/3 for complete usage.

Examples 

# Using an HTML template
%Email{}
|> put_phoenix_view(MyApp.Web.EmailView)
|> put_phoenix_template("welcome_email.html", user: user)

# Using a text template
%Email{}
|> put_phoenix_view(MyApp.Web.EmailView)
|> put_phoenix_template("welcome_email.txt", user: user)

# Using both an HTML and text template
%Email{}
|> put_phoenix_view(MyApp.Web.EmailView)
|> put_phoenix_template(:welcome_email, user: user)

# Setting the layout
%Email{}
|> put_phoenix_layout({MyApp.Web.EmailView, :layout})
|> put_phoenix_view(MyApp.Web.EmailView)
|> put_phoenix_template(:welcome_email, user: user)

Using a Default Phoenix View

You can set a default Phoenix View to use for rendering templates. Just set the :phoenix_view config value.

config :sendgrid,
  phoenix_view: MyApp.Web.EmailView

Using a Default View Layout

You can set a default layout to render the view in. Just set the :phoenix_layout config value.

config :sendgrid,
  phoenix_layout: {MyApp.Web.EmailView, :layout}

Link to this section Summary

Types

attachment()
content()
custom_args()
dynamic_template_data()
headers()
recipient()
substitutions()
t()

Functions

add_attachment(email, attachment)

Adds an attachment to the email

add_bcc(email, bcc_address)

Add recipients to the BCC address field. The bcc-name can be specified as the third parameter

add_bcc(email, bcc_address, bcc_name)
add_cc(email, cc_address)

Add recipients to the CC address field. The cc-name can be specified as the third parameter

add_cc(email, cc_address, cc_name)
add_custom_arg(email, arg_name, arg_value)

Adds a custom_arg value to the email

add_dynamic_template_data(email, arg_name, arg_value)

Adds a custom_arg value to the email

add_header(email, header_key, header_value)

Sets a custom header

add_personalization(email, personalization)

Adds a t:Personalization.t/0 to an email

add_substitution(email, sub_name, sub_value)

Adds a substitution value to be used with a template

add_to(email, to_address)

Sets the to field for the email. A to-name can be passed as the third parameter

add_to(email, to_address, to_name)
build()

Builds an an empty email to compose on

put_from(email, from_address)

Sets the from field for the email. The from-name can be specified as the third parameter

put_from(email, from_address, from_name)
put_html(email, html_body)

Sets the html content of the email

put_phoenix_layout(email, arg)

Sets the layout to use for the Phoenix Template

put_phoenix_template(email, template_name, assigns \\ [])

Renders the Phoenix template with the given assigns

put_phoenix_view(email, module)

Sets the Phoenix View to use

put_reply_to(email, reply_to_address)

Sets the reply_to field for the email. The reply-to name can be specified as the third parameter

put_reply_to(email, reply_to_address, reply_to_name)
put_send_at(email, send_at)

Sets a future date of when to send the email

put_subject(email, subject)

Sets the subject field for the email

put_template(email, template_id)

Uses a predefined SendGrid template for the email

put_text(email, text_body)

Sets text content of the email

set_sandbox(email, enabled?)

Sets the email to be sent with sandbox mode enabled or disabled

to_personalization(email)

Transforms an t:Email.t/0 to a t:Personalization.t/0

Link to this section Types

Link to this type attachment() View Source 
attachment() :: %{
  :content => String.t(),
  optional(:type) => String.t(),
  :filename => String.t(),
  optional(:disposition) => String.t(),
  optional(:content_id) => String.t()
}
Link to this type content() View Source 
content() :: %{type: String.t(), value: String.t()}
Link to this type custom_args() View Source 
custom_args() :: %{optional(String.t()) => String.t()}
Link to this type dynamic_template_data() View Source 
dynamic_template_data() :: %{optional(String.t()) => String.t()}
Link to this type headers() View Source 
headers() :: %{optional(String.t()) => String.t()}
Link to this type recipient() View Source 
recipient() :: %{:email => String.t(), optional(:name) => String.t()}
Link to this type substitutions() View Source 
substitutions() :: %{optional(String.t()) => String.t()}
Link to this type t() View Source 
t() :: %SendGrid.Email{
  __phoenix_layout__:
    nil | %{optional(:text) => String.t(), optional(:html) => String.t()},
  __phoenix_view__: nil | atom(),
  attachments: nil | [attachment()],
  bcc: nil | [recipient()],
  cc: nil | [recipient()],
  content: nil | [content()],
  custom_args: nil | custom_args(),
  dynamic_template_data: nil | dynamic_template_data(),
  from: nil | recipient(),
  headers: nil | headers(),
  personalizations: nil | [SendGrid.Personalization.t()],
  reply_to: nil | recipient(),
  sandbox: boolean(),
  send_at: nil | integer(),
  subject: nil | String.t(),
  substitutions: nil | substitutions(),
  template_id: nil | String.t(),
  to: nil | [recipient()]
}

Link to this section Functions

Link to this function add_attachment(email, attachment) View Source 
add_attachment(t(), attachment()) :: t()

Adds an attachment to the email.

An attachment is a map with the keys:

  • :content
  • :type
  • :filename
  • :disposition
  • :content_id

Examples 

attachment = %{content: "base64string", filename: "image.jpg"}
add_attachment(%Email{}, attachment}
Link to this function add_bcc(email, bcc_address) View Source 
add_bcc(t(), String.t()) :: t()

Add recipients to the BCC address field. The bcc-name can be specified as the third parameter.

Examples 

add_bcc(%Email{}, "test@email.com")
add_bcc(%Email{}, "test@email.com", "John Doe")
Link to this function add_bcc(email, bcc_address, bcc_name) View Source 
add_bcc(t(), String.t(), String.t()) :: t()
Link to this function add_cc(email, cc_address) View Source 
add_cc(t(), String.t()) :: t()

Add recipients to the CC address field. The cc-name can be specified as the third parameter.

Examples 

add_cc(%Email{}, "test@email.com")
add_cc(%Email{}, "test@email.com", "John Doe")
Link to this function add_cc(email, cc_address, cc_name) View Source 
add_cc(SendGrid.Email.t(), String.t(), String.t()) :: SendGrid.Email.t()
Link to this function add_custom_arg(email, arg_name, arg_value) View Source 
add_custom_arg(t(), String.t(), String.t()) :: t()

Adds a custom_arg value to the email.

If an argument for a given name is already set, it will be replaced when adding a argument with the same name.

Examples 

Email.add_custom_arg(%Email{}, "-sentIn-", "Elixir")
Link to this function add_dynamic_template_data(email, arg_name, arg_value) View Source 
add_dynamic_template_data(t(), String.t(), String.t()) :: t()

Adds a custom_arg value to the email.

If an argument for a given name is already set, it will be replaced when adding a argument with the same name.

Examples 

Email.add_dynamic_template_data(%Email{}, "-sentIn-", "Elixir")
Link to this function add_header(email, header_key, header_value) View Source 
add_header(t(), String.t(), String.t()) :: t()

Sets a custom header.

Examples 

Email.add_header(%Email{}, "HEADER_KEY", "HEADER_VALUE")
Link to this function add_personalization(email, personalization) View Source 
add_personalization(t(), SendGrid.Personalization.t()) :: t()

Adds a t:Personalization.t/0 to an email.

Link to this function add_substitution(email, sub_name, sub_value) View Source 
add_substitution(t(), String.t(), String.t()) :: t()

Adds a substitution value to be used with a template.

If a substitution for a given name is already set, it will be replaced when adding a substitution with the same name.

Examples 

Email.add_substitution(%Email{}, "-sentIn-", "Elixir")
Link to this function add_to(email, to_address) View Source 
add_to(t(), String.t()) :: t()

Sets the to field for the email. A to-name can be passed as the third parameter.

Examples 

add_to(%Email{}, "test@email.com")
add_to(%Email{}, "test@email.com", "John Doe")
Link to this function add_to(email, to_address, to_name) View Source 
add_to(t(), String.t(), String.t()) :: t()
Link to this function build() View Source 
build() :: t()

Builds an an empty email to compose on.

Examples 

iex> build()
%Email{...}
Link to this function put_from(email, from_address) View Source 
put_from(t(), String.t()) :: t()

Sets the from field for the email. The from-name can be specified as the third parameter.

Examples 

put_from(%Email{}, "test@email.com")
put_from(%Email{}, "test@email.com", "John Doe")
Link to this function put_from(email, from_address, from_name) View Source 
put_from(t(), String.t(), String.t()) :: t()
Link to this function put_html(email, html_body) View Source 
put_html(t(), String.t()) :: t()

Sets the html content of the email.

Examples 

Email.put_html(%Email{}, "<html><body><p>Sent from Elixir!</p></body></html>")
Link to this function put_phoenix_layout(email, arg) View Source 
put_phoenix_layout(t(), {atom(), atom()}) :: t()
put_phoenix_layout(t(), {atom(), String.t()}) :: t()

Sets the layout to use for the Phoenix Template.

Expects a tuple of the view module and layout to use. If you provide an atom as the second element, the text and HMTL versions of that template will be used for the respective content types.

Alernatively, you can set a default layout to use by setting the :phoenix_view key in your config as an atom which will be used for both text and HTML emails.

config :sendgrid,
  phoenix_layout: {MyApp.Web.EmailView, :layout}

Examples 

put_phoenix_layout(email, {MyApp.Web.EmailView, "layout.html"})
put_phoenix_layout(email, {MyApp.Web.EmailView, "layout.txt"})
put_phoenix_layout(email, {MyApp.Web.EmailView, :layout})
Link to this function put_phoenix_template(email, template_name, assigns \\ []) View Source 
put_phoenix_template(t(), atom(), list()) :: t()
put_phoenix_template(t(), String.t(), list()) :: t()

Renders the Phoenix template with the given assigns.

You can set the default Phoenix View to use for your templates by setting the :phoenix_view config value. Additionally, you can set the view on a per email basis by calling put_phoenix_view/2. Furthermore, you can have the template rendered inside a layout. See put_phoenix_layout/2 for more details.

Explicit Template Extensions

You can provide a template name with an explicit extension such as "some_template.html" or "some_template.txt". This is set the content of the email respective to the content type of the template rendered. For example, if you render an HTML template, the output of the rendering will be the HTML content of the email.

Implicit Template Extensions

You can omit a template’s extension and attempt to have both a text template and HTML template rendered. To have both types rendered, both templates must share the same base file name. For example, if you have a template named "some_template.txt" and a template named "some_template.html" and you call put_phoenix_template(email, :some_template), both templates will be used and will set the email content for both content types. The only caveat is both files must exist, otherwise you’ll have an exception raised.

Examples 

iex> put_phoenix_template(email, "some_template.html")
%Email{content: [%{type: "text/html", value: ...}], ...}

iex> put_phoenix_template(email, "some_template.txt", name: "John Doe")
%Email{content: [%{type: "text/plain", value: ...}], ...}

iex> put_phoenix_template(email, :some_template, user: user)
%Email{content: [%{type: "text/plain", value: ...}, %{type: "text/html", value: ...}], ...}
Link to this function put_phoenix_view(email, module) View Source 
put_phoenix_view(t(), atom()) :: t()

Sets the Phoenix View to use.

This will override the default Phoenix View if set in under the :phoenix_view config value.

Examples 

put_phoenix_view(email, MyApp.Web.EmailView)
Link to this function put_reply_to(email, reply_to_address) View Source 
put_reply_to(t(), String.t()) :: t()

Sets the reply_to field for the email. The reply-to name can be specified as the third parameter.

Examples 

put_reply_to(%Email{}, "test@email.com")
put_reply_to(%Email{}, "test@email.com", "John Doe")
Link to this function put_reply_to(email, reply_to_address, reply_to_name) View Source 
put_reply_to(t(), String.t(), String.t()) :: t()
Link to this function put_send_at(email, send_at) View Source 
put_send_at(t(), integer()) :: t()

Sets a future date of when to send the email.

Examples 

Email.put_send_at(%Email{}, 1409348513)
Link to this function put_subject(email, subject) View Source 
put_subject(t(), String.t()) :: t()

Sets the subject field for the email.

Examples 

put_subject(%Email{}, "Hello from Elixir")
Link to this function put_template(email, template_id) View Source 
put_template(t(), String.t()) :: t()

Uses a predefined SendGrid template for the email.

Examples 

Email.put_template(%Email{}, "the_template_id")
Link to this function put_text(email, text_body) View Source 
put_text(t(), String.t()) :: t()

Sets text content of the email.

Examples 

put_text(%Email{}, "Sent from Elixir!")
Link to this function set_sandbox(email, enabled?) View Source 
set_sandbox(t(), boolean()) :: t()

Sets the email to be sent with sandbox mode enabled or disabled.

The sandbox mode will default to what is explicity configured with SendGrid’s configuration.

Link to this function to_personalization(email) View Source 
to_personalization(t()) :: SendGrid.Personalization.t()

Transforms an t:Email.t/0 to a t:Personalization.t/0.