pablo-co/bamboo_postmark

A Bamboo adapter for Postmark

Bamboo.PostmarkAdapter

A Postmark adapter for the Bamboo email library.

Installation

The package can be installed by adding :bamboo_postmark to your list of dependencies in mix.exs:

def deps do
  # Get from hex
  [
    {:bamboo_postmark, "~> 1.0"}
  ]

  # Or use the latest from master
  [
    {:bamboo_postmark, github: "pablo-co/bamboo_postmark"}
  ]
end

Add your Postmark API key to your config. You can find this key as Server API token under the Credentials tab in each Postmark server.

# In your configuration file:
#  * General configuration: config/config.exs
#  * Recommended production only: config/prod.exs

config :my_app, MyApp.Mailer,
      adapter: Bamboo.PostmarkAdapter,
      api_key: "my_api_key"
      # Or if you want to use an ENV variable:
      # api_key: {:system, "POSTMARK_API_KEY"}

Follow Bamboo Getting Started Guide.

Using templates

The Postmark adapter provides a helper module for setting the template of an email.

defmodule MyApp.Mail do
  import Bamboo.PostmarkHelper

  def some_email do
    email
    |> template("id_of_template",
                %{name: "John Doe", confirm_link: "http://www.link.com"})
  end
end

Exception Warning

Postmark templates include a subject, HTML body and text body and thus these shouldn't be included in the email as they will raise an API exception.

email
|> template("id", %{value: "Some value"})
|> subject("Will raise exception")
|> html_body("<p>Will raise exception</p>")
|> text_body("Will raise exception")

Tagging emails

The Postmark adapter provides a helper module for tagging emails.

defmodule MyApp.Mail do
  import Bamboo.PostmarkHelper

  def some_email do
    email
    |> tag("some-tag")
  end
end

Sending extra parameters

You can send other extra parameters to Postmark with the put_param helper.

See Postmark's API for a complete list of parameters supported.

email
|> put_param("TrackLinks", "HtmlAndText")
|> put_param("TrackOpens", true)
|> put_param("Attachments", [
  %{
    Name: "file.txt",
    Content: "/some/file.txt" |> File.read!() |> Base.encode64(),
    ContentType: "txt"
  }
])

Changing the underlying request configuration

You can specify the options that are passed to the underlying HTTP client hackney by using the request_options key in the configuration.

Example

config :my_app, MyApp.Mailer,
      adapter: Bamboo.PostmarkAdapter,
      api_key: "my_api_key",
      request_options: [recv_timeout: 10_000]

JSON support

Bamboo comes with JSON support out of the box, see Bamboo JSON support.

Copyright and License

Copyright (c) 2016 Pablo Cárdenas

This library is released under the MIT License. See the LICENSE.md file.

bamboo_postmark's Issues

API Error with no details

Hello there, I am getting the following error, but it doesn’t really provide any insights into what the error actually is and I, therefore, can't figure out how to go about fixing it.

Running this code triggers the following error:

user |> MyApp.Email.password_reset("TOKEN") |> MyApp.Mailer.deliver_now()

** (Bamboo.PostmarkAdapter.ApiError) {:option, :server_only, :honor_cipher_order}
    (bamboo_postmark) lib/bamboo/postmark_adapter.ex:65: Bamboo.PostmarkAdapter.deliver/2
    (bamboo) lib/bamboo/mailer.ex:145: Bamboo.Mailer.deliver_now/4

The API key is present in the env and I’m able to pull it up using System.get_env(“MY_API_KEY”).
To make things extra fun, everything works as expected in development, but not in production even though dev/prod share the same configuration in this case.

In config.exs

config :my_app, MyApp.Mailer,
  adapter: Bamboo.PostmarkAdapter,
  api_key: System.get_env("POSTMARK_API_KEY")

Any pointers here would be greatly appreciated. I'd be open to opening a PR up if necessary, but perhaps I'm just missing something?

Thanks for your time 😊

Support reading api key from an env var

Support the config like:

config :my_app, MyApp.Mailer,
      adapter: Bamboo.PostmarkAdapter,
      api_key: {:system, "API_KEY"}

This is allowed in Sendgrid adapter.

Remove Poison Dependency

Bamboo comes with config :bamboo, :json_library, MyJsonLibrary. I'm wondering if it's possible to use that here instead of using poison.

Quoting recipient names with punctuation

First of all, thanks for the library.

I have a problem sending email to one of my customers who has included punctuation in their username. I use the to: [{user_name, user_email}] format to configure the recipient.

When the first field includes a comma e.g. acme, Inc, the postmark API returns the following error:

Here is the response:
"{\"ErrorCode\":300,\"Message\":\"Error parsing 'To': Illegal email address 'acme'. It must contain the '@' symbol.\"}"

Postmark's documentation states that

For email addresses that have names or titles with punctuation, you should quote them as such: "To" : ""Joe Receiver, jr" [email protected]"

ref

Do you think adding quote marks around the name of the recipient is within scope of this library?

Cheers

deliver/2 shouldn't throw exceptions

Hi, this may sound opinionated but IMHO I think the return of deliver/2 is inconsistent as I believe its a convention to append a ! (bang) to the routines that'll raise an exception. In other words, do you its sane to change the current deliver/2 to deliver!/2 and add another deliver/2 that'll return {:ok, %{status_code: status, headers: headers, body: response}} or {:error, :api_error}.

I understand that'll require change on the Bamboo codebase as well but what do you think?

P/S: I can help in submitting the PR should you agree to make the change.

put_params to put_params

Hi

in your example of additional parameters you should change put_paramS to put_param.

Another interesting point is, how you can add attachments with put_param

e.g. could be:

email
|> Bamboo.PostmarkHelper.put_param("Attachments",
   [
     %{
       Name: file.txt,
       Content: "/some/file.txt" |> File.read!() |> Base.encode64(),
       ContentType: "txt"
     }
   ])

it took a bit to figure out :)

thanks for the package!

Support for template alias

Hello there!

Is there already any plan to support TemplateAlias para instead of templateID?

Thanks!

Breaking changes coming to Bamboo v2.0.0

👋 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: beam-community/bamboo#572
• Mailgun changes: beam-community/bamboo#573
• Mandrill changes: 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.

Postmark disabling TLSv1.0 access

Will this Postmark Adapter still work with the upcoming TLS configuration changes coming down from Postmark?

Announced by Postmark here.

What’s changing

(1) Disable TLSv1.0 access,
(2) Disable all RC4 and low-strength ciphers
(3) Add HSTS headers

It looks like the postmark-rails changelog mentions they made a fix, see here. Will something similar need to be done?

Required callback supports_attachments? not implemented from Bamboo.Adapter

Bamboo just released a new version, and there are some changes to Bamboo.Adapter that cause compilation warnings. Specifically, a new callback was added:

@callback supports_attachments? :: boolean

The mailer implements this:

defp validate_attachment_support(%{attachments: []} = email, _adapter), do: email

defp validate_attachment_support(email, adapter) do
  if function_exported?(adapter, :supports_attachments?, 0) && adapter.supports_attachments? do
    email
  else
    raise "the #{adapter} does not support attachments yet."
  end
end

I don't think that this effects our codebase, because we don't send attachments as a part of our mailer. I thought you might want to know about this, though, to either pin bamboo to ~> 1.2.0 or implement the callback.

/cc @sax

Timeout configuration

We occasionally see timeouts when sending to the Postmark API. Is there a way to configure the max allowed timeout? Couldn't see an obvious way of doing it. Thanks! 😄

New release that includes the bug fix for attachments

Hi!

Can we please have a new release of the package that includes #31? :)

deliver function returns a #Reference in body

After the timeout/config update was released it is no longer possible to perform any operations the body contents received from the deliver function. Instead of getting a regular string inside body it includes a #Reference. I believe this is because the with_body is no longer passed to hackney. https://github.com/benoitc/hackney/blame/master/README.md#L174