gilacost / sendgrid_elixir

Create and send composable emails with Elixir and SendGrid.

SendGrid

A wrapper for SendGrid's API to create composable emails. Check the docs for complete usage.

Example

SendGrid.Email.build()
|> SendGrid.Email.add_to("[e-mail]")
|> SendGrid.Email.put_from("[e-mail]")
|> SendGrid.Email.put_subject("Hello from Elixir")
|> SendGrid.Email.put_text("Sent with Elixir")
|> SendGrid.Mail.send()

Installation

Add the following code to your dependencies in your mix.exs file:

{:sendgrid, "~> 2.0"}

Configuration

In one of your configuration files, include your SendGrid API key like this:

config :sendgrid,
  api_key: "SENDGRID_API_KEY"

If you want to use environment variable, use {:system, "ENV_NAME"} in your config:

config :sendgrid,
  api_key: {:system, "SENDGRID_API_KEY"}

If you'd like to enable sandbox mode (emails won't send but will be validated), add the setting to your config:

config :sendgrid,
  api_key: "SENDGRID_API_KEY",
  sandbox_enable: true

Add :sendgrid to your list of applications if using Elixir 1.3 or lower.

defp application do
  [applications: [:sendgrid]]
end

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 SendGrid.Email.put_phoenix_layout/2. See SendGrid.Email.put_phoenix_template/3 for complete usage.

Examples

import SendGrid.Email

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

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

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


# Setting the layout
%SendGrid.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 Layout

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

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

Personalizations

Personalizations are used to identify who should receive the email as well as specifics about how you would like the email to be handled.

Personalizations allow you to define:

• to, cc, bcc - The recipients of your email.
• subject - The subject of your email.
• headers - Any headers you would like to include in your email.
• substitutions - Any substitutions you would like to be made for your email.
• custom_args - Any custom arguments you would like to include in your email.
• dynamic_template_data - Data to send along with a template.
• send_at - A specific time that you would like your email to be sent.

An SendGrid.Email automatically takes these fields and transforms them into a personalization to be sent in the email. However, you can add multiple personalizations to an email and specify different handling instructions for different copies of your email. For example, you could send the same email to both [e-mail] and [e-mail], but set each email to be delivered at different times.

Example

alias SendGrid.{Mail, Email}
personalization_1 =
  Email.build()
  |> Email.add_to("[e-mail]")
  |> Email.put_subject("Exciting news!")
  |> Email.to_personalization()

personalization_2 =
  Email.build()
  |> Email.add_to("[e-mail]")
  |> Email.put_subject("We've some exciting news!")
  |> Email.to_personalization()

Email.build()
|> Email.put_from("[e-mail]")
|> Email.put_text("...")
|> Email.put_html("...")
|> Email.add_personalization(personalization_1)
|> Email.add_personalization(personalization_2)
|> Mail.send()

Limitations

The SendGrid v3 API limits you to 1,000 personalizations per API request. If you need to include more than 1,000 personalizations, please divide these across multiple API requests.

Testing

To run the unit tests you will need to create a config/config.exs file and provide your own SendGrid API and email address to receive a test email.

use Mix.Config

config :sendgrid,
  api_key: "<API_KEY>",
  phoenix_view: SendGrid.Email.Test.EmailView,
  test_address: "[e-mail]"

The config directory is excluded from the git repository so your API key and email address will not be committed.

Once configured you can run the full test suite including integration tests as follows:

mix test --include integration