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 configurationCustomization
Override this module in your application to customize email templates and delivery behavior while maintaining the same function signatures.
Summary
Functions
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).
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.
Deliver instructions to confirm account.
Warns user that their account is being hammered.
Deliver magic link registration instructions.
Deliver a "new login detected" security alert.
Deliver organization invitation email to a new (unregistered) user.
Deliver instructions to reset a user password.
Deliver instructions to update a user email.
Builds and delivers the welcome email to user in one call.
Functions
@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).
@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 instructions to confirm account.
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 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 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 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 instructions to reset a user password.
Deliver instructions to update a user email.
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.