|
| 1 | +Upgrading to Bamboo 2.0 |
| 2 | +======================= |
| 3 | + |
| 4 | +Bamboo 2.0 ships with some breaking changes (hence the major version bump). But |
| 5 | +don't worry, if you love Bamboo just as it is, there's an easy upgrade path. |
| 6 | + |
| 7 | +There are two breaking changes: |
| 8 | + |
| 9 | +- `Bamboo.Phoenix` extracted to [bamboo_phoenix] |
| 10 | +- `Bamboo.Mailer.deliver_now/2` and `deliver_later/2` don't raise on errors |
| 11 | + |
| 12 | +Let's cover each in turn. |
| 13 | + |
| 14 | +## Breaking change: `Bamboo.Phoenix` extracted to `bamboo_phoenix` |
| 15 | + |
| 16 | +`Bamboo.Phoenix` has been extracted to the [bamboo_phoenix] library. If you use |
| 17 | +`Bamboo.Phoenix` to render your email templates, add `bamboo_phoenix` to your |
| 18 | +dependencies: |
| 19 | + |
| 20 | +```elixir |
| 21 | +defp deps do |
| 22 | + [ |
| 23 | + ... |
| 24 | + {:bamboo, "~> 2.0"}, |
| 25 | + {:bamboo_phoenix, "~> 1.0"} |
| 26 | + ... |
| 27 | + ] |
| 28 | +end |
| 29 | +``` |
| 30 | + |
| 31 | +## Breaking change: `deliver_now/2`/`deliver_later/2` return `:ok` & `:error` tuples |
| 32 | + |
| 33 | +`Bamboo.Mailer`'s `deliver_now/2` and `deliver_later/2` no longer raise errors. |
| 34 | +Instead, they now return an `{:ok, email}` and `{:error, error}`, where the |
| 35 | +`error` is an exception struct or an error message. If you pass `response: |
| 36 | +true` as an argument, the return value will be `{:ok, email, response}`. |
| 37 | + |
| 38 | +If you prefer seeing code, this is the change in `@spec` signature for |
| 39 | +`deliver_now/2`: |
| 40 | + |
| 41 | +```diff |
| 42 | +- @spec deliver_now(Bamboo.Email.t(), Enum.t()) :: Bamboo.Email.t() | {Bamboo.Email.t(), any} |
| 43 | ++ @spec deliver_now(Bamboo.Email.t(), Enum.t()) :: |
| 44 | ++ {:ok, Bamboo.Email.t()} |
| 45 | ++ | {:ok, Bamboo.Email.t(), any} |
| 46 | ++ | {:error, Exception.t() | String.t()} |
| 47 | +``` |
| 48 | + |
| 49 | +Note that `deliver_later/2` will only return errors that happen _prior_ to |
| 50 | +scheduling the delivery of the email. What happens once the delivery is |
| 51 | +scheduled depends on what [delivery strategy] you are using. |
| 52 | + |
| 53 | +Those who want to handle errors on their own can now pattern match on the `:ok` |
| 54 | +and `:error` tuple responses. If you don't want to handle the errors and like |
| 55 | +how Bamboo behaves prior to 2.0, there's a simple upgrade path. 👇 |
| 56 | + |
| 57 | +### Simple upgrade path |
| 58 | + |
| 59 | +`Bamboo.Mailer` comes with `deliver_now!/2` and `deliver_later!/2`. Those two |
| 60 | +functions mirror the behavior that `deliver_now/2` and `deliver_later/2` had |
| 61 | +before 2.0. |
| 62 | + |
| 63 | +Hopefully, that makes for a simple upgrade path for those who don't want to |
| 64 | +handle the `{:ok, email}` and `{:error, error}` tuples. You only need to |
| 65 | +change: |
| 66 | + |
| 67 | +- `deliver_now/2` to `deliver_now!/2`, and |
| 68 | +- `deliver_later/2` to `deliver_later!/2` |
| 69 | + |
| 70 | +Note that `deliver_later!/2` will only raise email validation errors _before_ |
| 71 | +scheduling the email delivery. What happens after the delivery is scheduled |
| 72 | +depends on the [delivery strategy] you are using (e.g. |
| 73 | +`TaskSupervisorStrategy`). |
| 74 | + |
| 75 | +### `TaskSupervisorStrategy` |
| 76 | + |
| 77 | +Regardless of whether you use `deliver_later/2` or `deliver_later!/2`, if you |
| 78 | +use the `TaskSupervisorStrategy` for delivering emails, it will continue to |
| 79 | +raise errors when emails fail to be delivered. |
| 80 | + |
| 81 | +If you want control of those errors, you can implement a custom [delivery |
| 82 | +strategy], to handle errors coming from `adapter.deliver`. |
| 83 | + |
| 84 | +For now, `TaskSupervisorStrategy` continues to work as it did prior to `2.0`, |
| 85 | +so no change is needed here to upgrade to Bamboo 2.0. |
| 86 | + |
| 87 | +### Check with your adapter |
| 88 | + |
| 89 | +Each adapter needs to upgrade to satisfy the new [adapter.deliver callback]. |
| 90 | +Check with your adapter to see if it supports the new `ok` and `error` tuple |
| 91 | +API before upgrading to Bamboo 2.0. |
| 92 | + |
| 93 | +If you use SendGrid, Mailgun, or Mandrill, your adapter is already updated with |
| 94 | +Bamboo 2.0. |
| 95 | + |
| 96 | +That's it! For a full list of changes, please refer to the [changelog]. |
| 97 | + |
| 98 | +And if you find any issues with this upgrade guide, please let us know by |
| 99 | +[opening an issue] or submitting a pull-request. |
| 100 | + |
| 101 | +[adapter.deliver callback]: https://hexdocs.pm/bamboo/2.0.0/Bamboo.Adapter.html#c:deliver/2 |
| 102 | +[delivery strategy]: https://hexdocs.pm/bamboo/2.0.0/Bamboo.DeliverLaterStrategy.html |
| 103 | +[opening an issue]: https://github.com/thoughtbot/bamboo/issues |
| 104 | +[bamboo_phoenix]: https://hexdocs.pm/bamboo_phoenix |
| 105 | +[changelog]: https://github.com/thoughtbot/bamboo/blob/master/CHANGELOG.md |
0 commit comments