# Rivet Email

A simple to use templated email system as part of the [Rivets Framework](https://docs.google.com/document/d/1ntoTA9YRE7KvKpmwZRtfzKwTZNgo2CY6YfJnDNQAlBc). Key things to using this:

* `Backend` — this is what we use for the actual heavy lifting. For now, using Bamboo mailer.
* `Mailer` — the entrypoint/API used in other apps
* *templates* — templates to handle messages
* *config* — where you specify the Mailer module
* *data structs* — uses Rivet.Ident.Email and Rivet.Ident.User, but anything can be subbed in

Usage steps (see examples that follow for more detail):

1. Configure Rivet Email (see `config/config.exs` for an example of supported configurations).
2. Create Mailer and Email modules as well as one or more templates (see `lib/email/examples`).
3. Send email, where `recips` can be a single or list of `user_model`, `email_model` or an ID for a `user_model`:

```elixir
MyEmail.send(recips, MyEmailTemplate)
```

## Rivet Mailer and Email modules

```elixir
defmodule MyEmailBackend do
  use Rivet.Email.Mailer, otp_app: :app_name_here
end
```

```elixir
defmodule MyEmail do
  use Rivet.Email,
    otp_app: :app_name_here,
    backend: MyEmailBackend,
    user_model: Ident.User, # optional; shown with default
    email_model: Ident.Email # optional; shown with default
end
```

Config:

```elixir
config :rivet_email,
  enabled: true,
  mailer: MyEmail
```

## Template

The template defines a generate() function, which accepts the recipient as a UserEmailStruct,
and attributes as a map. Attributes come from the configuration

```elixir
defmodule Myapp.Email.AuthErrorTemplate do
  @behaviour Rivet.Email.Template

  @impl Rivet.Email.Template
  def generate(recip, attrs) do
    {:ok, "failed", "<p>Sorry #{recip.user.name}<p>This didn't work"}
  end

  # create a "send" function (optional), and then call it as:
  #   AuthErrorTemplate.send(recipients)
  def send(recip) do
    # gather attributes and do things here
    # then send:
    Rivet.Email.mailer().send(recip, __MODULE__, attrib1: value, ...)
  end
end
```

## Rivet User and Email structs

The included structures should at least support:

```elixir
  %UserStruct{
    id: String.t(),
    emails: list(UserEmailStruct.t()),
  }
  %UserEmailStruct{
    id: String.t(),
    address: String.t()
    user: UserStruct.t()
  }
```

And, each structure should have a `one/1` function that accepts an `id: ID`
keyword pair, as well as a `preload/2` function that accepts the relevant
struct and a list of atoms for fields to preload (per Ecto's preload).