# `PhoenixKit.Users.Auth.UserNotifier`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v2.55.1/lib/phoenix_kit/users/auth/user_notifier.ex#L1)

User notification system for PhoenixKit authentication workflows.

This module handles email delivery for user authentication and account management workflows,
including account confirmation, password reset, and email change notifications.

## Email Types

- **Confirmation instructions**: Sent during user registration
- **Password reset instructions**: Sent when user requests password reset
- **Email update instructions**: Sent when user changes their email address

## Configuration

Configure your mailer in your application config:

    config :phoenix_kit, PhoenixKit.Mailer,
      adapter: Swoosh.Adapters.SMTP,
      # ... other adapter configuration

## Customization

Override this module in your application to customize email templates
and delivery behavior while maintaining the same function signatures.

# `build_welcome`

```elixir
@spec build_welcome(map()) :: Swoosh.Email.t()
```

The welcome email for `user`, built but not sent — so
`PhoenixKit.Users.WelcomeEmailWorker` can tell a failure before the mailer
(nothing sent) from one during delivery (unknown).

# `deliver_built`

```elixir
@spec deliver_built(Swoosh.Email.t()) :: {:ok, Swoosh.Email.t()} | {:error, term()}
```

Hands a message built here (`build_welcome/1`) to the mailer — the
configured parent application mailer if there is one, otherwise
PhoenixKit's built-in one.

`{:error, reason}` means the mailer refused it: it was not sent.

# `deliver_confirmation_instructions`

Deliver instructions to confirm account.

# `deliver_failed_login_alert`

Warns `user` that their account is being hammered.

Sent when failures cross `failed_login_alert_threshold` inside an hour, at
most once a day per account — `PhoenixKit.Users.LoginAttempts` owns both
gates. Unlike the new-device alert, nothing here means a sign-in SUCCEEDED;
the point is to reach the reader while it is still only attempts.

# `deliver_magic_link_registration`

Deliver magic link registration instructions.

Accepts a user struct or a bare address: on this path the account does not
exist yet, so there may be no stored locale preference to resolve.

# `deliver_new_login_alert`

Deliver a "new login detected" security alert.

Sent by `PhoenixKit.Users.LoginAlerts` when a login is seen from a
device (IP + user-agent pair) not previously associated with the
account. `attrs` carries `:ip_address`, `:browser`, `:os` (either may be
`nil`), `:location` (a "City, Country" string, or `nil` if geolocation
didn't resolve), and `:first_seen_at` (a `DateTime`).

# `deliver_organization_invitation`

Deliver organization invitation email to a new (unregistered) user.

Sends a registration link containing the invitation token so the invitee
can register and automatically join the organization on email confirmation.

# `deliver_reset_password_instructions`

Deliver instructions to reset a user password.

# `deliver_update_email_instructions`

Deliver instructions to update a user email.

# `deliver_welcome`

Builds and delivers the welcome email to `user` in one call.

The welcome email itself is sent by `PhoenixKit.Users.WelcomeEmailWorker`
(see `PhoenixKit.Users.WelcomeEmail` for when and how often), which uses
`build_welcome/1` and `deliver_built/1` separately.

---

*Consult [api-reference.md](api-reference.md) for complete listing*