Breaking changes coming to Bamboo v2.0.0

[germsvel]

👋 Hi Pablo,

Thanks for maintaining this Bamboo adapter. 🥳

There will be a breaking change coming to Bamboo in v2.0.0 where the deliver_now function will no longer raise an error on failure to deliver an email. Instead, it will return :ok or :error tuples. That way, users of the library can decide how to handle the errors. I've completed that work in beam-community/bamboo#571.

I've also added a deliver_now! function that is meant to behave exactly as deliver_now currently behaves. So, there's an easy upgrade path for users who don't want to handle their own errors. They can change deliver_now -> deliver_now!.

(There are also deliver_later corresponding changes, but from the adapter's perspective, I don't know that it matters).

What that means for adapters

In order for people to upgrade to Bamboo v2.0.0, the adapters will need to stop raising errors when they fail to deliver emails. In order to accommodate that, the adapter's callbacks are changing like this:

- @callback deliver(%Bamboo.Email{}, %{}) :: any
+ @callback deliver(%Bamboo.Email{}, %{}) :: {:ok, any} | {:error, Exception.t() | String.t()}

In other words, adapters should now return an {:ok, response} tuple or an {:error, error} tuple, where the error is either an exception struct that can later be raised or an error message.

To facilitate that work, PR 571 also introduces a Bamboo.ApiError.build_api_error function that can be used by adapters — if you want to easily build an error to return in the {:error, error} response.

Sample changes to other adapters

I have already done some changes to the Sendgrid, Mailgun, and Mandrill adapters. They might serve as a guide:

• Sendgrid changes: Update SendGrid Adapter to return ok/error tuple beam-community/bamboo#572
• Mailgun changes: Update Mailgun.deliver to return ok/error tuples beam-community/bamboo#573
• Mandrill changes: Update Mandrill to return ok/error tuples beam-community/bamboo#574

Why open this issue?

I wanted to open this issue for two reasons:

1. To let you know about the changes that are coming up (all of the above), and
2. To ask you if there's anything I can do to help with the transition.

Unfortunately, I can't offer to open PRs to make the changes in all the adapter repos, but if it's helpful, I'd be happy to review PRs.

And if there's some change to Bamboo that would make it easier to work with your adapter, or if you have suggestions or comments on PR 571, I'd love to know.

Thanks again for maintaining this adapter, and please feel free to close this issue whenever you've read it (if it's of no further use). It just seemed like the easiest way to communicate about the upcoming changes with you.

[mdlkxzmcp]

@pablo-co the aforementioned 2.0 has already gone live. If you want, I'd be willing to try to make a PR for this as there is not a lot of things that need to be done :)

[pablo-co]

@mdlkxzmcp if you can open that PR I'm happy to merge and publish. 😄

[samhamilton]

@pablo-co would you mind cutting a new release on hex so its possible to upgrade to Bamboo 2.0?

[pablo-co]

@samhamilton was waiting for another possible breaking change regarding TLS certificates to release as V1.0.0. Though it appears that PR won't be necessary, so will cut a release with just this PR 👍

[edds]

@pablo-co hey, did a release get cut that includes this? Would be super useful for us so we can interrogate error messages.

[pablo-co]

Sorry for the delay @edds. Just released v1.0.0 with these changes.