diff --git a/docs/config/env.md b/docs/config/env.md
index 9bb133fa..745b63ad 100644
--- a/docs/config/env.md
+++ b/docs/config/env.md
@@ -172,6 +172,29 @@ Enables the Nextcloud-compatible API layer (`/remote.php/`, `/ocs/`, `/status.ph
 | `OXICLOUD_NEXTCLOUD_INSTANCE_ID` | `ocnca` | Instance ID suffix used in `oc:id` formatting |
 | `OXICLOUD_NEXTCLOUD_VERSION` | `28.0.4` | Emulated Nextcloud version reported to clients (format: `major.minor.patch`) |
 
+## Outbound Email (SMTP)
+
+Used by the magic-link invitation flow and the login-via-email flow. When `OXICLOUD_SMTP_HOST` is empty (the default), the feature is disabled and any endpoint that needs email returns 503.
+
+| Variable | Default | Description |
+|---|---|---|
+| `OXICLOUD_SMTP_HOST` | — | SMTP server hostname or IP. Empty disables the feature. |
+| `OXICLOUD_SMTP_PORT` | `587` | Submission port (587 STARTTLS, 465 implicit TLS, 25 plain) |
+| `OXICLOUD_SMTP_USER` | — | SASL username. Leave empty for anonymous relay. |
+| `OXICLOUD_SMTP_PASS` | — | SASL password |
+| `OXICLOUD_SMTP_FROM` | — | `From:` mailbox; bare address or RFC 5322 name-address (`OxiCloud <noreply@example.com>`) |
+| `OXICLOUD_SMTP_TLS` | `starttls` | Transport encryption: `starttls`, `tls`, or `none` (emits startup WARN) |
+
+## Magic-Link Authentication
+
+Configures the invite-by-email and login-via-email flows. Both require SMTP to be configured above.
+
+| Variable | Default | Description |
+|---|---|---|
+| `OXICLOUD_MAGIC_LINK_TTL_HOURS` | `24` | Lifetime of a freshly-minted magic-link token, in hours |
+| `OXICLOUD_ALLOW_EXTERNAL_USERS` | `true` | Kill switch for the whole flow. `false` makes `POST /api/grants` reject `subject.type = "email"` for unknown addresses and `POST /api/auth/magic-link/send` return its uniform stub without issuing a token. |
+| `OXICLOUD_EXTERNAL_EMAIL_DOMAINS` | — | Comma-separated allowlist of email domains accepted when minting a new external user (case-insensitive, exact match on the post-`@` part). Empty = any domain is allowed, subject to `OXICLOUD_ALLOW_EXTERNAL_USERS`. Subdomains must be listed explicitly: `partner.com` does NOT match `eng.partner.com`. Example: `partner-a.com,partner-b.io`. |
+
 ## Trusted Proxy
 
 | Variable | Default | Description |
diff --git a/example.env b/example.env
index 3c175407..58d8fbe8 100644
--- a/example.env
+++ b/example.env
@@ -311,6 +311,71 @@ OXICLOUD_WOPI_ENABLED=false
 # Clients use this to decide which protocol features to enable.
 #OXICLOUD_NEXTCLOUD_VERSION=28.0.4
 
+# -----------------------------------------------------------------------------
+# OUTBOUND EMAIL (SMTP)
+# -----------------------------------------------------------------------------
+#
+# Used by the magic-link invitation flow (sharing with someone by email) and
+# the login-via-email flow. When HOST is empty (the default), the feature is
+# disabled and any endpoint that needs email returns 503.
+
+# SMTP server hostname or IP. Empty = feature disabled.
+#OXICLOUD_SMTP_HOST=smtp.example.com
+
+# Submission port. Common values:
+#   587 = STARTTLS submission (default)
+#   465 = implicit TLS submission
+#    25 = plain relay (development only)
+#OXICLOUD_SMTP_PORT=587
+
+# SASL username for SMTP AUTH. Leave empty for anonymous relay.
+#OXICLOUD_SMTP_USER=oxicloud@example.com
+
+# SASL password. Logged as `<set>` / `<anon>` in startup banner (never echoed
+# in plaintext).
+#OXICLOUD_SMTP_PASS=
+
+# `From:` mailbox. Either a bare address or RFC 5322 name-address form.
+#OXICLOUD_SMTP_FROM=OxiCloud <noreply@example.com>
+
+# Transport encryption mode:
+#   starttls = port 587 with STARTTLS upgrade (default — recommended)
+#   tls      = implicit TLS from the first byte (port 465)
+#   none     = no encryption; emits a startup WARN, development only
+#OXICLOUD_SMTP_TLS=starttls
+
+# -----------------------------------------------------------------------------
+# MAGIC-LINK AUTHENTICATION
+# -----------------------------------------------------------------------------
+#
+# Knobs for the invite-by-email / login-via-email flows. Both rely on SMTP
+# being configured above.
+
+# Lifetime of a freshly-minted magic-link token, in hours. After this, the
+# background sweeper marks the token expired. Must be > 0.
+#OXICLOUD_MAGIC_LINK_TTL_HOURS=24
+
+# Kill switch for the whole magic-link flow.
+#   true  = POST /api/grants accepts `subject.type = "email"`; new external
+#           users are created lazily and invitation mails are sent.
+#   false = the same call returns 403; POST /api/auth/magic-link/send
+#           returns the uniform stub response without issuing a token.
+# This is the coarse "turn it all off" switch; the per-domain allowlist
+# below is the fine-grained version.
+#OXICLOUD_ALLOW_EXTERNAL_USERS=true
+
+# Allowlist of email domains accepted when minting a new external user.
+# Comma-separated, case-insensitive, exact-match on the post-`@` part of the
+# address. Empty (the default) = any domain is allowed, subject to
+# OXICLOUD_ALLOW_EXTERNAL_USERS above.
+#
+# Wildcards / subdomain semantics are intentionally NOT supported:
+# `partner.com` does not match `eng.partner.com`. List every subdomain
+# explicitly when needed.
+#
+# Example (only addresses on these two domains can be invited):
+#OXICLOUD_EXTERNAL_EMAIL_DOMAINS=partner-a.com,partner-b.io
+
 # -----------------------------------------------------------------------------
 # PROXY
 # -----------------------------------------------------------------------------