Bamboo.GmailAdapter

Gmail adapter for Bamboo

Quick Links

Preconditions
Installation
Configuration
Documentation
Contribute

Motivation

Why not just use SMTP?

Starting in 2020, Google is deprecating the use of its Gmail API with SMTP usage. This adapter allows GSuite account holders to use Bamboo in light of this deprecation by using OAuth2 for authentication.

Preconditions

There are a few preconditions that must be met before this adapter can be used to send email:

Admin access to a Google Workspace account (NOTE: your personal Gmail accounts WILL NOT WORK)
Enable Gmail API GCP Console
Implement server-side authorization using Service Account credentials

Don't give any GCP roles for the service account.
Add your Google Workspace email as a user, as servicer account Owner role.
If you have other Domain aliases, add those alias users in https://mail.google.com/mail/u/2/#settings/accounts, in "Send mail as"

Grant the service account domain-wide authority

first do here: https://console.cloud.google.com/iam-admin/serviceaccounts, by clicking the service account, and going to Domain Wide Delegation
Service account will create a related OAuth2.0 client id.

Authorize API client with required scopes here: https://admin.google.com/u/2/ac/owl/domainwidedelegation

The scope that you need to add is: https://www.googleapis.com/auth/gmail.send

Installation

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

def deps do
  [
    {:bamboo_gmail, "~> 0.2.0"}
  ]
end

Some application settings must be configured. See the example section below.

Configuration

Setting	Description	Required?
`adapter`	Bamboo adapter in use (`Bamboo.GmailAdapter`).	Yes
`sub`	Email address the service account is impersonating (address the email is sent from). If impersonation is not needed, then `nil` (it is likely needed).	Yes
`sandbox`	Development mode that does not send email. Details of the API call are instead output to the elixir console.	No
`json`	Google auth crendentials must be provided in JSON format to the `:goth` app. These are generated in the Google Developers Console.	Yes

Note:

Secrets such as the service account sub, and the auth credentials should not be commited to version control.

Instead, pass in via environment variables using a tuple:

{:system, "SUB_ADDRESS"}

Or read in from a file:

"creds.json" |> File.read!

Example Config

config :app_name, GmailAdapterTestWeb.Mailer,
  adapter: Bamboo.GmailAdapter,
  sub: {:system, "SUB_ADDRESS"},
  sandbox: false

# Google auth credentials must be provided to the `goth` app
config :goth, json: {:system, "GCP_CREDENTIALS"}

Documentation

Docs can be found at https://hexdocs.pm/bamboo_gmail.

Contribute

Contribution Guidelines can be found here. Please feel free to use, share, and extend this project. PR's welcome.

parkerduckworth/bamboo_gmail