Optional email delivery (SMTP)

SMTP configuration is optional. You can sign up, sign in, write, organize, and search in a basic local installation without a mail server. The default is DTXWIKI_MAIL_PROVIDER=none. Local use at http://127.0.0.1:21080/ does not need Gmail or an app password. A shared server's sign-up policy remains a separate setting.

Configure SMTP for account-email verification, email password recovery, one-time identity confirmation, or adding an account email. This page is for the server operator who controls how dtxWiki starts; workspace ownership alone does not grant that access.

What changes when mail is enabled

Setup	Account behavior
Mail disabled, basic local HTTP	Email verification and email password recovery are unavailable. Follow Members and access for account and operator procedures.
Mail disabled, canonical HTTPS URL configured	The operator can provide an administrator-assisted one-time recovery link. SMTP is still optional.
SMTP and canonical HTTPS URL configured	Signed-in users can request email verification. Eligible active accounts with a verified address can request password-reset email. Signed-in active accounts with a registered email can request identity-confirmation email even if that address has not been verified. Email-less accounts can add an email when password login is also enabled.

For a sensitive account or server-admin action, the offered email confirmation link lasts five minutes and must be opened in the same browser session; it confirms that purpose and does not extend session freshness indefinitely. This is separate from a password-reset link and its expiry.

Account → Login methods → Add account email also needs SMTP and password login enabled. An email-less SSO account opens the sent confirmation in the same signed-in browser to register the address. SMTP alone does not create a local password or replace the IdP login method.

Adding a workspace member is separate and does not promise an invitation email. SMTP does not enable Google sign-in or an AI app's MCP connection.

An account-mail request is saved in an outbox, a sending queue. The background worker sends it through the configured SMTP provider. Locally, that is the worker dtxwiki starts for itself; on a server, it is the dtxwiki-worker service or the Compose worker service. Gmail receives the recipient address and message, including the one-time account link. See Privacy and safe sharing.

Prepare the server first

1. Confirm that the server is already reachable at its real HTTPS address. Set DTXWIKI_PUBLIC_BASE_URL to that address, such as https://wiki.example.com. This setting does not create a domain, certificate, or reverse proxy; follow Server deployment first.
2. Locally, the worker started by dtxwiki automatically uses the app's installation and settings. A separate worker service must use the same installation, database, data directory, and session secret as the app, so it can read the queued messages. An unrelated worker cannot replace it.
3. Choose a sender account you control and an account whose inbox you can check. Replace the placeholder addresses below.

Settings → Deployment → Identity & Recovery shows the provider, sender, canonical URL, redacted credential status, outbox counts, and last observed delivery. It displays operator commands; it is not an SMTP password editor or a test-email button. Apply settings through the process environment or production configuration, then restart dtxWiki: restart dtxwiki locally, restart both systemd services, or recreate the Docker app and worker containers.

Gmail example

The main example uses smtp.gmail.com with 587 and STARTTLS. The alternative is 465 with SSL/TLS. dtxWiki requires exactly one transport mode. Google's SMTP protocol reference documents the host and ports.

Setting	Value
DTXWIKI_MAIL_PROVIDER	smtp
DTXWIKI_MAIL_FROM_ADDRESS	Your full Gmail address, for example your-gmail-address@gmail.com
DTXWIKI_SMTP_HOST	smtp.gmail.com
DTXWIKI_SMTP_USERNAME	The same full Gmail address
DTXWIKI_SMTP_PASSWORD	A Google app password for this application
DTXWIKI_PUBLIC_BASE_URL	Your existing dtxWiki HTTPS address

Secure connection	Port	DTXWIKI_SMTP_STARTTLS	DTXWIKI_SMTP_USE_SSL
STARTTLS	587	true	false
SSL/TLS from connection start	465	false	true

Create an app password

1. Sign in to the Google account that will send mail and enable 2-Step Verification.
2. Open Google Account → App passwords. Name the application dtxWiki SMTP and create a password.
3. Keep it in your approved secrets store and use it for SMTP, instead of your usual Google account password.

App passwords may be unavailable for work/school accounts, security-key-only 2-Step Verification, or Advanced Protection. Check policy or choose another allowed SMTP service; do not disable account protections. dtxWiki uses username/password SMTP authentication, not Gmail OAuth. Google revokes app passwords after an account-password change: replace the secret and restart dtxWiki. Revoke unused app passwords. Google's app-password guide, Advanced Protection restrictions.

systemd: save production settings

These commands use the existing production installation's protected /etc/dtxwiki/dtxwiki.env. Run them in Bash on the server. Replace the HTTPS URL and sender first. Keep the provider none while changing transport settings, then select smtp last to avoid an invalid intermediate combination.

sudo dtxwiki config set DTXWIKI_MAIL_PROVIDER=none
sudo dtxwiki config set DTXWIKI_PUBLIC_BASE_URL=https://wiki.example.com
sudo dtxwiki config set DTXWIKI_MAIL_FROM_ADDRESS=your-gmail-address@gmail.com
sudo dtxwiki config set DTXWIKI_SMTP_HOST=smtp.gmail.com
sudo dtxwiki config set DTXWIKI_SMTP_PORT=587
sudo dtxwiki config set DTXWIKI_SMTP_STARTTLS=true
sudo dtxwiki config set DTXWIKI_SMTP_USE_SSL=false
sudo dtxwiki config set DTXWIKI_SMTP_USERNAME=your-gmail-address@gmail.com
IFS= read -r -s -p 'Gmail app password: ' gmail_app_password
printf '\n'
sudo dtxwiki config set "DTXWIKI_SMTP_PASSWORD=$gmail_app_password" --i-understand
unset gmail_app_password
sudo dtxwiki config set DTXWIKI_MAIL_PROVIDER=smtp
sudo systemctl restart dtxwiki dtxwiki-worker

The hidden prompt keeps the literal password out of shell history. The existing CLI briefly passes the value as a process argument; use an operator-controlled terminal with command tracing disabled. Do not paste secrets into shared examples, issues, or screenshots. The password command requires --i-understand; config show redacts its stored value.

Writing configuration does not update running processes. After restarting both services, check:

sudo dtxwiki config show
sudo systemctl status dtxwiki dtxwiki-worker --no-pager

Reopen Identity & Recovery. Its configured state checks settings, not whether Gmail accepted a message or a recipient received it. Complete the delivery check below.

For 465, set DTXWIKI_SMTP_PORT=465, DTXWIKI_SMTP_STARTTLS=false, and DTXWIKI_SMTP_USE_SSL=true while the provider is none, then select smtp and restart both services.

Manual starts: terminal environment

Use these examples only with an already working HTTPS endpoint. They affect the current terminal and do not persist production configuration. Stop the existing dtxWiki before starting it with new settings. Keep the existing data-directory and session-secret settings.

Choose the command for your installation method. The environment examples below finish with the Python-installed app command; npm users replace that last line with the npm command. The app starts its own background worker with the same settings, and that worker sends the queued mail, so one terminal is enough. See Access and background operation.

Installation	Command for the last line
Python tool installed with pipx or uv	dtxwiki --no-open
npm launcher (with uv or pipx)	npx @dtxsuite/dtxwiki@0.2.1 serve --no-open

Bash on Linux or macOS

export DTXWIKI_PUBLIC_BASE_URL=https://wiki.example.com
export DTXWIKI_MAIL_PROVIDER=smtp
export DTXWIKI_MAIL_FROM_ADDRESS=your-gmail-address@gmail.com
export DTXWIKI_SMTP_HOST=smtp.gmail.com
export DTXWIKI_SMTP_PORT=587
export DTXWIKI_SMTP_STARTTLS=true
export DTXWIKI_SMTP_USE_SSL=false
export DTXWIKI_SMTP_USERNAME=your-gmail-address@gmail.com
IFS= read -r -s -p 'Gmail app password: ' gmail_app_password
printf '\n'
export DTXWIKI_SMTP_PASSWORD="$gmail_app_password"
unset gmail_app_password
dtxwiki --no-open

Open the server through HTTPS. The background worker of this dtxwiki process reads the same exports and sends the queued mail; no second terminal is needed. A new terminal does not inherit these exports, so restart dtxWiki from this terminal or repeat the assignments. Stop dtxWiki with Ctrl+C. Clear the secret with unset DTXWIKI_SMTP_PASSWORD when finished; clearing a variable does not change an already-running process.

PowerShell for manual Windows use

$env:DTXWIKI_PUBLIC_BASE_URL = "https://wiki.example.com"
$env:DTXWIKI_MAIL_PROVIDER = "smtp"
$env:DTXWIKI_MAIL_FROM_ADDRESS = "your-gmail-address@gmail.com"
$env:DTXWIKI_SMTP_HOST = "smtp.gmail.com"
$env:DTXWIKI_SMTP_PORT = "587"
$env:DTXWIKI_SMTP_STARTTLS = "true"
$env:DTXWIKI_SMTP_USE_SSL = "false"
$env:DTXWIKI_SMTP_USERNAME = "your-gmail-address@gmail.com"
$gmailAppPassword = Read-Host "Gmail app password" -AsSecureString
$env:DTXWIKI_SMTP_PASSWORD = [System.Net.NetworkCredential]::new("", $gmailAppPassword).Password
Remove-Variable gmailAppPassword
dtxwiki --no-open

The background worker started by the last line uses the same settings, so no second PowerShell window is needed. Preserve the same data-directory and session-secret settings. This is a manual-start example; official production hosting targets Linux. After stopping dtxWiki with Ctrl+C, clear the secret with Remove-Item Env:DTXWIKI_SMTP_PASSWORD.

Docker Compose

In an existing production Compose installation, put the Gmail table's settings in the private infra/prod/.env. Enter the password in a protected editor or approved secrets workflow. Keep DTXWIKI_DOMAIN set to the working HTTPS domain; Compose derives the public URL from it. The bundled Compose file passes mail settings to both app and worker; the worker service sends the queued mail.

From that Compose directory, apply the changed environment:

docker compose up -d --force-recreate app worker

A simple container restart does not apply changed Compose environment values. Do not share .env or attach docker compose config output publicly; it can contain resolved secrets.

Confirm actual delivery

Check your own server with an account you control. The configuration examples are instructions, not a claim that external Gmail delivery has been tested for your installation.

1. Sign in to an active account whose inbox you can read. Open Account, then Verify email if the address is unverified.
2. Check inbox and spam folders. Open the newest verification message; confirm that its link uses your real dtxWiki HTTPS domain. Complete verification and check for Email verified on the account page.
3. As a server administrator, inspect Identity & Recovery: last observed delivery and queued/failed counts. Provider acceptance is useful evidence; also confirm arrival in the inbox.
4. If you test password recovery, use Forgot your password? for this verified account and complete the latest link. The reset page asks for a new password of 8–128 characters; spaces count. This changes the account: public self-service recovery revokes browser sessions and API/MCP/OAuth credentials. Reconnect that account's tools afterward.

The public reset response does not disclose whether an address is registered or eligible. A request-accepted message alone is not proof of sending. See Members and access for operator-assisted recovery and delivery choices.

Troubleshooting

What you see	Next check
No Verify email	SMTP and canonical HTTPS must be configured; an already-verified address needs no request.
No Google App passwords option	Check 2-Step Verification and account restrictions; choose another allowed provider if needed.
Gmail rejects authentication	Use the full sender address and app password. Changing the Google account password revokes earlier app passwords.
SMTP transport error	Choose 587 / STARTTLS true / SSL false, or 465 / STARTTLS false / SSL true.
Mail remains queued	Locally, the worker runs inside dtxwiki: restart it from a terminal that has the SMTP settings. On a server, check that the dtxwiki-worker service or the worker container is running with the same database, data directory, secret and SMTP settings as the app. Restart both after changes.
Link points elsewhere or uses HTTP	Correct DTXWIKI_PUBLIC_BASE_URL, restart dtxWiki (both services or containers on a server), then request a new message.
Failed delivery or no inbox message	Check outbound SMTP-port access, credentials, provider restrictions, recipient address, and spam filtering. Use the newest message after correcting the cause.
Reset request accepted but no mail	The target must be an eligible active account with a verified address. Ask the operator to inspect recovery status.

To disable mail, set DTXWIKI_MAIL_PROVIDER=none in the configuration that starts dtxWiki, then restart it (both services or containers on a server). Revoke the unused Google app password. Mail-free use remains available; administrator-assisted links still require the canonical HTTPS URL.

---

Version evidence: mail settings, SMTP and outbox, account recovery, configuration CLI, worker, worker started by the app, Compose environment.