emails

Ready-made emails for auth, sent with howdy/mail: one template for each auth.Purpose, and one for MFA codes. Replace any of them with your own.

import howdy/auth
import howdy/auth/emails
import howdy/auth/mfa

let auth_emails = emails.new(mailer, app_name: "Acme")
let assert Ok(identity) =
  auth.new(repo:, origin:, deliver: emails.deliver(auth_emails))
let mfa_config = mfa.with_delivery(config, emails.deliver_mfa(auth_emails))

Each message goes to the delivery’s address and is tagged auth.<purpose>, such as auth.sign_in, so it is easy to find in the admin outbox. previews gives the admin a preview of every template.

A token, link or code is only revealed into the message body. A failed send is logged without it, and the auth flow reports the failure.

The default templates are written in the delivery’s locale (see auth.with_locales), in English when there is none or no translation. Their words live in auth/locales/emails/*.json; after editing them, regenerate howdy/auth/internal/emails_messages with cd i18n && gleam run -m howdy/i18n/cli -- gen --locales=../auth/locales/emails --out=../auth/src/howdy/auth/internal/emails_messages.gleam.

Types

Emails

opaque </>

pub opaque type Emails

Values

default

</>

pub fn default(
  app_name: String,
  delivery: auth.Delivery,
) -> mail.Message

The default message for a delivery, without its recipient, in the delivery’s locale.

default_mfa

</>

pub fn default_mfa(
  app_name: String,
  code: secret.Secret,
  locale: option.Option(String),
) -> mail.Message

The default MFA code message, without its recipient, in locale if it is given.

deliver

</>

pub fn deliver(
  emails: Emails,
) -> fn(auth.Delivery) -> Result(Nil, Nil)

The function auth.new and auth.with_email_tokens take.

deliver_mfa

</>

pub fn deliver_mfa(
  emails: Emails,
) -> fn(user.User, secret.Secret) -> Result(Nil, Nil)

The function mfa.with_delivery takes.

message

</>

pub fn message(
  emails: Emails,
  delivery: auth.Delivery,
) -> mail.Message

The message for a delivery: yours if with_template gave one for its purpose, otherwise the default.

mfa_message

</>

pub fn mfa_message(
  emails: Emails,
  email: String,
  code: secret.Secret,
  locale: option.Option(String),
) -> mail.Message

The MFA code message, in locale if it is given.

new

</>

pub fn new(
  mailer: mail.Mailer,
  app_name app_name: String,
) -> Emails

The default templates, naming the app app_name, sent with mailer.

previews

</>

pub fn previews(emails: Emails) -> List(preview.Preview)

A preview of every template, grouped under “Auth”, with made-up tokens, links and codes sent to someone@example.com.

previews_in

</>

pub fn previews_in(
  emails: Emails,
  locales: List(String),
) -> List(preview.Preview)

Previews of every template in each of locales, such as ["de", "ja"], grouped under “Auth (de)” and so on, to check translations in the admin.

purpose_name

</>

pub fn purpose_name(purpose: auth.Purpose) -> String

sign_in, registration and so on.

with_mfa_template

</>

pub fn with_mfa_template(
  emails: Emails,
  build: fn(String, secret.Secret, option.Option(String)) -> mail.Message,
) -> Emails

Build the MFA code email yourself, from the address, the code and the recipient’s locale, if they have one.

with_template

</>

pub fn with_template(
  emails: Emails,
  for purpose: auth.Purpose,
  build build: fn(auth.Delivery) -> mail.Message,
) -> Emails

Build the email for one purpose yourself. Set the subject and body; the recipient and the auth.<purpose> tag are added for you.