diff --git a/CODE_GUIDELINES.md b/CODE_GUIDELINES.md
index 18036db..53662e2 100644
--- a/CODE_GUIDELINES.md
+++ b/CODE_GUIDELINES.md
@@ -1255,32 +1255,32 @@ mix deps.update phoenix
mix hex.outdated
```
-### 3.11 Email: Swoosh
+### 3.11 Email: Swoosh and Phoenix.Swoosh
-**Mailer Configuration:**
+**Mailer and from address:**
+
+- `Mv.Mailer` (Swoosh) and `Mv.Mailer.mail_from/0` return the configured sender `{name, email}`.
+- Config: `config :mv, :mail_from, {"Mila", "noreply@example.com"}` in config.exs; override in runtime.exs from ENV for production.
+
+**Unified layout (transactional emails):**
+
+- All transactional emails (join confirmation, user confirmation, password reset) use the same layout: `MvWeb.EmailLayoutView` (layout) and `MvWeb.EmailsView` (body templates).
+- Templates live under `lib/mv_web/templates/emails/` (bodies) and `lib/mv_web/templates/emails/layouts/` (layout). Use Gettext in templates for i18n.
+- See `MvWeb.Emails.JoinConfirmationEmail`, `Mv.Accounts.User.Senders.SendNewUserConfirmationEmail`, `SendPasswordResetEmail` for the pattern; see `docs/email-layout-mockup.md` for layout structure.
+
+**Sending with layout:**
```elixir
-defmodule Mv.Mailer do
- use Swoosh.Mailer, otp_app: :mv
-end
-```
+use Phoenix.Swoosh, view: MvWeb.EmailsView, layout: {MvWeb.EmailLayoutView, "layout.html"}
-**Sending Emails:**
-
-```elixir
-defmodule Mv.Accounts.WelcomeEmail do
- use Phoenix.Swoosh, template_root: "lib/mv_web/templates"
- import Swoosh.Email
-
- def send(user) do
- new()
- |> to({user.name, user.email})
- |> from({"Mila", "noreply@mila.example.com"})
- |> subject("Welcome to Mila!")
- |> render_body("welcome.html", %{user: user})
- |> Mv.Mailer.deliver()
- end
-end
+new()
+|> from(Mailer.mail_from())
+|> to(email_address)
+|> subject(gettext("Subject"))
+|> put_view(MvWeb.EmailsView)
+|> put_layout({MvWeb.EmailLayoutView, "layout.html"})
+|> render_body("template_name.html", %{assigns})
+|> Mailer.deliver!()
```
### 3.12 Internationalization: Gettext
diff --git a/config/config.exs b/config/config.exs
index d4de2c2..323f5cd 100644
--- a/config/config.exs
+++ b/config/config.exs
@@ -89,6 +89,10 @@ config :mv, MvWeb.Endpoint,
# at the `config/runtime.exs`.
config :mv, Mv.Mailer, adapter: Swoosh.Adapters.Local
+# Default mail "from" address for transactional emails (join confirmation,
+# user confirmation, password reset). Override in config/runtime.exs from ENV.
+config :mv, :mail_from, {"Mila", "noreply@example.com"}
+
# Configure esbuild (the version is required)
config :esbuild,
version: "0.17.11",
diff --git a/config/runtime.exs b/config/runtime.exs
index 93df5bb..d502cfa 100644
--- a/config/runtime.exs
+++ b/config/runtime.exs
@@ -219,6 +219,10 @@ if config_env() == :prod do
# ## Configuring the mailer
#
+ # Transactional emails (join confirmation, user confirmation, password reset) use
+ # the sender from config :mv, :mail_from. Override in production if needed:
+ # config :mv, :mail_from, {System.get_env("MAIL_FROM_NAME", "Mila"), System.get_env("MAIL_FROM_EMAIL", "noreply@example.com")}
+ #
# In production you need to configure the mailer to use a different adapter.
# Also, you may need to configure the Swoosh API client of your choice if you
# are not using SMTP. Here is an example of the configuration:
diff --git a/docs/development-progress-log.md b/docs/development-progress-log.md
index 5d777ff..4e95ff4 100644
--- a/docs/development-progress-log.md
+++ b/docs/development-progress-log.md
@@ -800,6 +800,14 @@ end
- Domain: `Mv.Membership.submit_join_request/2`, `Mv.Membership.confirm_join_request/2` (token hashing via `JoinRequest.hash_confirmation_token/1`, lookup, expiry check, idempotency for :submitted/:approved/:rejected).
- Test file: `test/membership/join_request_test.exs` – all tests pass; policy test and expired-token test implemented.
+**Subtask 2 – Submit and confirm flow (done):**
+- **Unified email layout:** phoenix_swoosh with `MvWeb.EmailLayoutView` (layout) and `MvWeb.EmailsView` (body templates). All transactional emails (join confirmation, user confirmation, password reset) use the same layout. Config: `config :mv, :mail_from, {name, email}` (default `{"Mila", "noreply@example.com"}`); override in runtime.exs.
+- **Join confirmation:** Domain wrapper `submit_join_request/2` generates token (or uses optional `:confirmation_token` in attrs for tests), creates JoinRequest via action `:submit`, then sends one email via `MvWeb.Emails.JoinConfirmationEmail`. Route `GET /confirm_join/:token` (JoinConfirmController) updates to `submitted`; idempotent; expired/invalid handled.
+- **Senders migrated:** `SendNewUserConfirmationEmail`, `SendPasswordResetEmail` use layout + `Mv.Mailer.mail_from/0`.
+- **Cleanup:** Mix task `mix join_requests.cleanup_expired` hard-deletes JoinRequests in `pending_confirmation` with expired `confirmation_token_expires_at` (authorize?: false). For cron/Oban.
+- **Gettext:** New email strings in default domain; German translations in de/LC_MESSAGES/default.po.
+- Tests: `join_request_test.exs`, `join_request_submit_email_test.exs`, `join_confirm_controller_test.exs` – all pass.
+
### Test Data Management
**Seed Data:**
diff --git a/docs/email-layout-mockup.md b/docs/email-layout-mockup.md
new file mode 100644
index 0000000..0c1d53b
--- /dev/null
+++ b/docs/email-layout-mockup.md
@@ -0,0 +1,26 @@
+# Unified Email Layout – ASCII Mockup
+
+All transactional emails (join confirmation, user confirmation, password reset) use the same layout.
+
+```
++------------------------------------------------------------------+
+| [Logo or app name – e.g. "Mila" or club name] |
++------------------------------------------------------------------+
+| |
+| [Subject / heading line – e.g. "Confirm your email address"] |
+| |
+| [Body content – paragraph and CTA link] |
+| e.g. "Please click the link below to confirm your request." |
+| "Confirm my request" (button or link) |
+| |
+| [Optional: short note – e.g. "If you didn't request this, |
+| you can ignore this email."] |
+| |
++------------------------------------------------------------------+
+| [Footer – one line, e.g. "© 2025 Mila · Mitgliederverwaltung"] |
++------------------------------------------------------------------+
+```
+
+- **Header:** Single line (app/club name), subtle.
+- **Main:** Heading + body text + primary CTA (link/button).
+- **Footer:** Single line, small text (copyright / product name).
diff --git a/lib/membership/membership.ex b/lib/membership/membership.ex
index d967b38..ffca356 100644
--- a/lib/membership/membership.ex
+++ b/lib/membership/membership.ex
@@ -30,6 +30,7 @@ defmodule Mv.Membership do
import Ash.Expr
alias Ash.Error.Query.NotFound, as: NotFoundError
alias Mv.Membership.JoinRequest
+ alias MvWeb.Emails.JoinConfirmationEmail
admin do
show? true
@@ -85,7 +86,7 @@ defmodule Mv.Membership do
end
resource Mv.Membership.JoinRequest do
- define :submit_join_request, action: :submit
+ # submit_join_request/2 implemented as custom function below (create + send email)
end
end
@@ -350,6 +351,47 @@ defmodule Mv.Membership do
|> then(&Ash.read_one(query, &1))
end
+ @doc """
+ Creates a join request (submit flow) and sends the confirmation email.
+
+ Generates a confirmation token if not provided in attrs (e.g. for tests, pass
+ `:confirmation_token` to get a known token). On success, sends one email with
+ the confirm link to the request email.
+
+ ## Options
+ - `:actor` - Must be nil for public submit (policy allows only unauthenticated).
+
+ ## Returns
+ - `{:ok, request}` - Created JoinRequest in status pending_confirmation
+ - `{:error, error}` - Validation or authorization error
+ """
+ def submit_join_request(attrs, opts \\ []) do
+ actor = Keyword.get(opts, :actor)
+ token = Map.get(attrs, :confirmation_token) || generate_confirmation_token()
+
+ attrs_with_token =
+ attrs |> Map.drop([:confirmation_token]) |> Map.put(:confirmation_token, token)
+
+ case Ash.create(JoinRequest, attrs_with_token,
+ action: :submit,
+ actor: actor,
+ domain: __MODULE__
+ ) do
+ {:ok, request} ->
+ JoinConfirmationEmail.send(request.email, token)
+ {:ok, request}
+
+ error ->
+ error
+ end
+ end
+
+ defp generate_confirmation_token do
+ 32
+ |> :crypto.strong_rand_bytes()
+ |> Base.url_encode64(padding: false)
+ end
+
@doc """
Confirms a join request by token (public confirmation link).
diff --git a/lib/mix/tasks/join_requests.cleanup_expired.ex b/lib/mix/tasks/join_requests.cleanup_expired.ex
new file mode 100644
index 0000000..bc9ea2a
--- /dev/null
+++ b/lib/mix/tasks/join_requests.cleanup_expired.ex
@@ -0,0 +1,56 @@
+defmodule Mix.Tasks.JoinRequests.CleanupExpired do
+ @moduledoc """
+ Hard-deletes JoinRequests in status `pending_confirmation` whose confirmation link has expired.
+
+ Retention: records with `confirmation_token_expires_at` older than now are deleted.
+ Intended for cron or Oban (e.g. every hour). See docs/onboarding-join-concept.md.
+
+ ## Usage
+
+ mix join_requests.cleanup_expired
+
+ ## Examples
+
+ $ mix join_requests.cleanup_expired
+ Deleted 3 expired join request(s).
+ """
+ use Mix.Task
+
+ require Ash.Query
+
+ alias Mv.Membership.JoinRequest
+
+ @shortdoc "Deletes join requests in pending_confirmation with expired confirmation token"
+
+ @impl Mix.Task
+ def run(_args) do
+ Mix.Task.run("app.start")
+
+ now = DateTime.utc_now()
+
+ query =
+ JoinRequest
+ |> Ash.Query.filter(status == :pending_confirmation)
+ |> Ash.Query.filter(confirmation_token_expires_at < ^now)
+
+ # Bypass authorization: cleanup is a system maintenance task (cron/Oban).
+ case Ash.read(query, domain: Mv.Membership, authorize?: false) do
+ {:ok, requests} ->
+ count = delete_expired_requests(requests)
+ Mix.shell().info("Deleted #{count} expired join request(s).")
+ count
+
+ {:error, error} ->
+ Mix.raise("Failed to list expired join requests: #{inspect(error)}")
+ end
+ end
+
+ defp delete_expired_requests(requests) do
+ Enum.reduce_while(requests, 0, fn request, acc ->
+ case Ash.destroy(request, domain: Mv.Membership, authorize?: false) do
+ :ok -> {:cont, acc + 1}
+ {:error, _} -> {:halt, acc}
+ end
+ end)
+ end
+end
diff --git a/lib/mv/accounts/user/senders/send_new_user_confirmation_email.ex b/lib/mv/accounts/user/senders/send_new_user_confirmation_email.ex
index 2135465..7c5fa0c 100644
--- a/lib/mv/accounts/user/senders/send_new_user_confirmation_email.ex
+++ b/lib/mv/accounts/user/senders/send_new_user_confirmation_email.ex
@@ -1,12 +1,20 @@
defmodule Mv.Accounts.User.Senders.SendNewUserConfirmationEmail do
@moduledoc """
Sends an email for a new user to confirm their email address.
+
+ Uses the unified email layout (MvWeb.EmailsView + EmailLayoutView) and
+ central mail from config (Mv.Mailer.mail_from/0).
"""
use AshAuthentication.Sender
- use MvWeb, :verified_routes
+ use Phoenix.Swoosh,
+ view: MvWeb.EmailsView,
+ layout: {MvWeb.EmailLayoutView, "layout.html"}
+
+ use MvWeb, :verified_routes
import Swoosh.Email
+ use Gettext, backend: MvWeb.Gettext, otp_app: :mv
alias Mv.Mailer
@@ -26,21 +34,16 @@ defmodule Mv.Accounts.User.Senders.SendNewUserConfirmationEmail do
"""
@impl true
def send(user, token, _) do
+ confirm_url = url(~p"/confirm_new_user/#{token}")
+ subject = gettext("Confirm your email address")
+
new()
- # Replace with email from env
- |> from({"noreply", "noreply@example.com"})
+ |> from(Mailer.mail_from())
|> to(to_string(user.email))
- |> subject("Confirm your email address")
- |> html_body(body(token: token))
+ |> subject(subject)
+ |> put_view(MvWeb.EmailsView)
+ |> put_layout({MvWeb.EmailLayoutView, "layout.html"})
+ |> render_body("user_confirmation.html", %{confirm_url: confirm_url, subject: subject})
|> Mailer.deliver!()
end
-
- defp body(params) do
- url = url(~p"/confirm_new_user/#{params[:token]}")
-
- """
- Click this link to confirm your email:
- #{url}
- """
- end
end
diff --git a/lib/mv/accounts/user/senders/send_password_reset_email.ex b/lib/mv/accounts/user/senders/send_password_reset_email.ex
index bcf4e75..a4bb489 100644
--- a/lib/mv/accounts/user/senders/send_password_reset_email.ex
+++ b/lib/mv/accounts/user/senders/send_password_reset_email.ex
@@ -1,12 +1,20 @@
defmodule Mv.Accounts.User.Senders.SendPasswordResetEmail do
@moduledoc """
- Sends a password reset email
+ Sends a password reset email.
+
+ Uses the unified email layout (MvWeb.EmailsView + EmailLayoutView) and
+ central mail from config (Mv.Mailer.mail_from/0).
"""
use AshAuthentication.Sender
- use MvWeb, :verified_routes
+ use Phoenix.Swoosh,
+ view: MvWeb.EmailsView,
+ layout: {MvWeb.EmailLayoutView, "layout.html"}
+
+ use MvWeb, :verified_routes
import Swoosh.Email
+ use Gettext, backend: MvWeb.Gettext, otp_app: :mv
alias Mv.Mailer
@@ -26,21 +34,16 @@ defmodule Mv.Accounts.User.Senders.SendPasswordResetEmail do
"""
@impl true
def send(user, token, _) do
+ reset_url = url(~p"/password-reset/#{token}")
+ subject = gettext("Reset your password")
+
new()
- # Replace with email from env
- |> from({"noreply", "noreply@example.com"})
+ |> from(Mailer.mail_from())
|> to(to_string(user.email))
- |> subject("Reset your password")
- |> html_body(body(token: token))
+ |> subject(subject)
+ |> put_view(MvWeb.EmailsView)
+ |> put_layout({MvWeb.EmailLayoutView, "layout.html"})
+ |> render_body("password_reset.html", %{reset_url: reset_url, subject: subject})
|> Mailer.deliver!()
end
-
- defp body(params) do
- url = url(~p"/password-reset/#{params[:token]}")
-
- """
- Click this link to reset your password:
- #{url}
- """
- end
end
diff --git a/lib/mv/mailer.ex b/lib/mv/mailer.ex
index 43d5c39..3d83636 100644
--- a/lib/mv/mailer.ex
+++ b/lib/mv/mailer.ex
@@ -1,3 +1,19 @@
defmodule Mv.Mailer do
+ @moduledoc """
+ Swoosh mailer for transactional emails.
+
+ Use `mail_from/0` for the configured sender address (join confirmation,
+ user confirmation, password reset).
+ """
use Swoosh.Mailer, otp_app: :mv
+
+ @doc """
+ Returns the configured "from" address for transactional emails.
+
+ Configure in config.exs or runtime.exs as `config :mv, :mail_from, {name, email}`.
+ Default: `{"Mila", "noreply@example.com"}`.
+ """
+ def mail_from do
+ Application.get_env(:mv, :mail_from, {"Mila", "noreply@example.com"})
+ end
end
diff --git a/lib/mv_web/emails/email_layout_view.ex b/lib/mv_web/emails/email_layout_view.ex
new file mode 100644
index 0000000..a0cf03f
--- /dev/null
+++ b/lib/mv_web/emails/email_layout_view.ex
@@ -0,0 +1,12 @@
+defmodule MvWeb.EmailLayoutView do
+ @moduledoc """
+ Layout view for transactional emails (join confirmation, user confirmation, password reset).
+
+ Renders a single layout template that wraps all email body content.
+ See docs/email-layout-mockup.md for the layout structure.
+ """
+ use Phoenix.View,
+ root: "lib/mv_web",
+ path: "templates/emails/layouts",
+ namespace: MvWeb
+end
diff --git a/lib/mv_web/emails/emails_view.ex b/lib/mv_web/emails/emails_view.ex
new file mode 100644
index 0000000..87bb29d
--- /dev/null
+++ b/lib/mv_web/emails/emails_view.ex
@@ -0,0 +1,13 @@
+defmodule MvWeb.EmailsView do
+ @moduledoc """
+ View for transactional email body templates.
+
+ Templates are rendered inside EmailLayoutView layout when sent via Phoenix.Swoosh.
+ """
+ use Phoenix.View,
+ root: "lib/mv_web",
+ path: "templates/emails",
+ namespace: MvWeb
+
+ use Gettext, backend: MvWeb.Gettext, otp_app: :mv
+end
diff --git a/lib/mv_web/emails/join_confirmation_email.ex b/lib/mv_web/emails/join_confirmation_email.ex
new file mode 100644
index 0000000..f72ec45
--- /dev/null
+++ b/lib/mv_web/emails/join_confirmation_email.ex
@@ -0,0 +1,33 @@
+defmodule MvWeb.Emails.JoinConfirmationEmail do
+ @moduledoc """
+ Sends the join request confirmation email (double opt-in) using the unified email layout.
+ """
+ use Phoenix.Swoosh,
+ view: MvWeb.EmailsView,
+ layout: {MvWeb.EmailLayoutView, :layout}
+
+ use MvWeb, :verified_routes
+ import Swoosh.Email
+ use Gettext, backend: MvWeb.Gettext, otp_app: :mv
+
+ alias Mv.Mailer
+
+ @doc """
+ Sends the join confirmation email to the given address with the confirmation link.
+
+ Called from the domain after a JoinRequest is created (submit flow).
+ """
+ def send(email_address, token) when is_binary(email_address) and is_binary(token) do
+ confirm_url = url(~p"/confirm_join/#{token}")
+ subject = gettext("Confirm your membership request")
+
+ new()
+ |> from(Mailer.mail_from())
+ |> to(email_address)
+ |> subject(subject)
+ |> put_view(MvWeb.EmailsView)
+ |> put_layout({MvWeb.EmailLayoutView, "layout.html"})
+ |> render_body("join_confirmation.html", %{confirm_url: confirm_url, subject: subject})
+ |> Mailer.deliver!()
+ end
+end
diff --git a/lib/mv_web/templates/emails/join_confirmation.html.heex b/lib/mv_web/templates/emails/join_confirmation.html.heex
new file mode 100644
index 0000000..b8344eb
--- /dev/null
+++ b/lib/mv_web/templates/emails/join_confirmation.html.heex
@@ -0,0 +1,18 @@
+
+
+ {gettext(
+ "We have received your membership request. To complete it, please click the link below."
+ )}
+
+
+
+ {gettext("Confirm my request")}
+
+
+
+ {gettext("If you did not submit this request, you can ignore this email.")}
+
+
+
+ |
+ Mila
+ |
+
+
+ |
+ {@inner_content}
+ |
+
+
+ |
+ © {DateTime.utc_now().year} Mila · Mitgliederverwaltung
+ |
+
+
+
+
diff --git a/lib/mv_web/templates/emails/password_reset.html.heex b/lib/mv_web/templates/emails/password_reset.html.heex
new file mode 100644
index 0000000..8dece57
--- /dev/null
+++ b/lib/mv_web/templates/emails/password_reset.html.heex
@@ -0,0 +1,18 @@
+
+
+ {gettext("You requested a password reset. Click the link below to set a new password.")}
+
+
+
+ {gettext("Reset password")}
+
+
+
+ {gettext(
+ "If you did not request this, you can ignore this email. Your password will remain unchanged."
+ )}
+
+
+
+ {gettext("Please confirm your email address by clicking the link below.")}
+
+
+
+ {gettext("Confirm my email")}
+
+
+
+ {gettext("If you did not create an account, you can ignore this email.")}
+
+