thoughtbot/bamboo

Testable, composable, and adapter based Elixir email library for devs that love piping.

bamboo's Issues

Raise if the Mandrill response is not successful

Add ability to add attachments

This is probably going to come a bit later since I have never needed to send an attachment in an email, it's always a link back to the app. I know this is useful to people though so it should be added.

assert_delivered_email with options

Usually assert_delivered_email(Email.welcome_email(user) will work fine, but there are cases when it won't

I think I should add assert_delivered_email(subject: "Something") in case you can't/don't want to assert against a whole email.

This would be helpful if parts of the email have state that would make it difficult to test the whole email. For example, if a token is generated in the text/html_body from Phoenix.Token, then the body would be different every time since the token would change. So it might be better to assert just a few of the most important fields.

Improve folder naming

@scrogson suggested improving the folder names for clarity

I would create lib/bamboo/adapters
move mandrill_adapter.ex to lib/bamboo/adapters/mandrill.ex
same for the test_adapter.ex
make lib/bamboo/adapters/mandrill/email.ex
and lib/bamboo/adapters/test/mailbox.ex
and update the module names accordingly

Add nice error when you forget the options in Bamboo.Phoenix

use Bamboo.Phoenix should be raise a helpful error if the view is not added. Almost done with this

Should deliver and deliver_async noop if all recipients are blank?

While using this in one of our applications we had to do something like this

users = Repo.all(User)

if length(users) > 0 do
  Emails.welcome_email(users) |> Mailer.deliver_async
end

Maybe deliver_async should throw a warning? Maybe an option to allow empty_recipients?

deliver_async(allow_empty_recipients: true)

Maybe this could be done at the mailer level via an option?

defmodule MyApp.Mailer do
  use Bamboo.Mailer, otp_app: :my_app

  @allow_empty_recipients true
end

Add SMTPAdapter

Possible libraries to use

• https://github.com/nurugger07/hermes
• https://github.com/antp/mailer

Should the Mandrill adapter use one of the API client available on Hex

It feels like it would be nicer if the adapters were not coupled to the bamboo codebase.

What do you think?

Add plug that shows list of emails in SentEmail

Great for viewing sent emails in dev

Fix options with assert_delivered_email

It should normalize the email addresses, and should only match against the keys that are in the options. For asserting just what you pass in, do something like this

defmacro assert_delivered_email(email_params) do
    # Normalize the address as well
    quote do
      import ExUnit.Assertions
      assert_received({:delivered_email, unquote(email_params)})
    end
  end

Rename Formatter.format_recipient and pass type of email

Instead have Bamboo.EmailAddress.format It should also have a second argument that is passed a keyword list (or maybe a map) that contains what type of address it is (from, cc, bcc, to)

That way you can do something like

defimpl Bamboo.EmailAddress, for: MyApp.User do
  # Add the app's name when sending the email from a user
  def format(user, %{type: :from}) do
    %{name: "#{user.name} (NameOfApp)", address: user.address}
  end

  def format(user, _opts) do
    %{name: user.name, address: user.address
  end
end

Define a start_link so that Async deliveries can be supervised with Task.Supervisor

Make it easier to render emails with layouts

See https://github.com/phoenixframework/phoenix/blob/740bda4250f17944ae12661e2905724cf0fd00df/lib/phoenix/view.ex#L170 for how to do that. Maybe allow setting a default layout use Bamboo.Phoenix, view: EmailView, layout: {LayoutView, "email.html"}. Also add function like put_layout?

Don't parse all config opts at compile time

Instead grab the adapter and other info (API key, etc.) at runtime. This makes it easier to change during tests, or while using in iex. That way you can switch to a TestAdapter or LocalAdapter long enough to send some tests emails and then switch it back if you wanted to. Also would clean up the Bamboo tests

EDIT: I'm not totally sure about this. Probably going to hold off on it for a bit

Consider renaming deliver_async to deliver_later or background_deliver

When switching to #52 it might make sense to rename the function

Use struct!/2 when creating emails

So it raises if you pass keys that don't exist in the Bamboo.Email struct. Also required elixir 1.2

Add a function to easily add merge vars using the MandrillAdapter

The merge vars can be pretty handy but it's a pain to use them. Something like

email |> put_merge_params(users, fn(user) -> %{first_name: user.first_name} end)

Change DeliverImmediatelyStrategy to ImmediateDeliveryStrategy

Change TestAdapter to LocalAdapter

That way it can be used for test and dev environments

Raise helpful error if you forget to start the test_mailbox

Change TestMailbox to SentEmail

Switch from `Bamboo.EmailAddress` to two item tuples

Much easier to work with, and easier to see what's going on at a glance. I've started work on this and it's almost done

Remove implicit MyApp.EmailView and let them set it as an option

https://github.com/paulcsmith/bamboo/blob/master/lib/bamboo/phoenix.ex#L14

Remove that and let people set it like this

use Bamboo.Phoenix, render_with: MyApp.EmailView

Raise helpful error if render_with is not set

Remove format_email_address from use Bamboo.Test

Add send grid adapter to readme

https://github.com/mtwilliams/bamboo-sendgrid

Add Mailgun adapter

Add an adapter for the Mailgun API

I'm starting on this one.

Have a way to whitelist emails from the config

Great for use in staging environments

  whitelist_emails: System.get_env("WHITELIST_EMAILS") # if nil, [] or "" then it will allow all emails

Remove use Mandrill.Email

It only imports two modules and most people won't use this that much (usually will have just a couple email modules). So I think it's better to just let people import the modules they need.

This is almost done

Make TestMailbox.one wait

If you use deliver_async TestMailbox.one will often fail because the email hasn't quite been sent yet. The Mailbox should wait a bit. Maybe using receive

Add Bamboo.Test

This will

• alias Bamboo.SentEmail
• import Bamboo.Formatter.format_recipient
• Add a setup block that calls SentEmail.reset

If delivery fails when calling deliver_later, log the error

So you can see that something went wrong

Raise if there is no html or text unless you explicitly set them both to empty

This makes it easier to find out when you accidentally forget to render the body, but still allows you to leave it empty if you really want to.

The reason that you might want to set empty html and text bodies is that some adapters may be used to render emails from another service. For example, you can use Mandrill to render responsive templates that are rendered on their server, so you would not set a text or html body

Add callbacks for mailer adapters

Don't use Task.async in deliver_async

Task.async is linking the task process with the parent process so if the latter dies first it will kill the former.

For example, with Phoenix it would mean that a HTTP request could finish before we actually had a chance to send the email.

Elixir 1.2 introduced Task.async_no_link which could be used here.

Happy to submit a PR if you think that's the way to go.

More explicit phoenix template rendering

Right now view rendering uses Phoenix.View.render_existing which is ok except that it can make it easy to think you're sending an email with both formats, but in reality you had a typo in a template name and you only send a text or html version. Instead I think this should be more explicit so you get more immediate and helpful feedback.

Right now you do: render("template_name") which will render a text or html template if it exists

Instead I think it should be render("template_name.html") and render("template_name.text") if you have just one type of template to send.

If you want to send text and html then you would do render(:template_name) and it will render both and raise if either one is missing.

Add assert_one_email_sent/1

Would work something like this

assert_one_email_sent Emails.welcome_email(user)

Remove API key from errors in MandrillAdapter

That API key should be removed from the errors if it is anything but nil or an empty string. We don't want keys accidentally leaked into the logs

Use more reliable async task

I think Task.Supervisor.start_child should do the trick. Task.start_link links to the caller process and if the caller process dies, so does the background task. This is probably not preferred.

Add docs to all the functions/modules people will use

Ensure SentEmail restarts when there is an error

Change nil on %Email{from} to %UnknowMailbox{}

nil doesn't really mean much so it can be hard to figure out where it's coming from and what it means. Instead the default should be a struct like %UnknownMailbox{} or %UnsetMailbox{}. Something along those lines

Update README

Add actual code

Raise helpful error when you try to send something that's not an email struct

Don't require a specific type of deliver_later_strategy when using LocalAdapter

Extract helpers for fake servers

https://github.com/paulcsmith/bamboo/blob/master/test/lib/bamboo/mandrill_adapter_test.exs#L17

Could probably make a new hex package out of this actually

Change deliver to deliver_now for delivering right away

I think this makes the library a bit easier to use. That way deliver uses the strategy you want and if you want to deliver right away then you use deliver_sync. This essentially flips how the current mailer works.

Still not 100% sold on the name though. Function name ideas:

• deliver_now
• deliver_sync
• deliver_blocking (though it's not really blocking so maybe a bad name)

Only compile Bamboo.Phoenix if Phoenix is loaded

So that Phoenix is not required to use Bamboo

Make sure task worker is added

I wonder if there should be some way to test that the task worker is added so you don't deploy to prod and find out that you forgot to add the Bamboo.TaskSupervisor to your supervisor.

Raise if API key is nil in MandrillAdapter

Add instructions so that the test adapter is reset after each test

Or maybe tie the test mailbox to the process so that each new process has a fresh mailbox? Not really sure quite yet