Mail: a service panel, and email that looks like OxygenHub cd46e56b1709

Andy (2026-10-14) wanted mail set up by picking a service, generic for
any installation, and messages that look good.

Administration › Mail is a panel (#181): pick Resend (its API key),
Amazon SES (region and SES SMTP credentials), Mailgun (us or eu and the
SMTP login), another SMTP server (server, port, security, user,
password), an SMTP URL for anything else (file:// for development), or
Off. Every service is SMTP underneath: the panel stores one standard
SMTP URL, so any provider works. Keys are never shown again; left empty
the saved one stays while service, server and user do. An smtp:// URL
that says nothing of TLS now requires STARTTLS (lettre's default was
none), except to a relay on this machine.

Every message goes as plain text and HTML (#182): the Oxygen band with
the mark sent inline (cid:logo, shows without loading images), the
subject as heading, the body with links, the message's action as a
button where its link stood (link beneath for clients hiding buttons),
and a footer of Explore, Help, Notification settings and Stop these
emails. Email-safe tables and inline styles with dark-mode colours.
Verification, reset, notification and test messages each get a button.

Tested: services compose and read back their URLs (keys kept, never
carried to another service); the panel saves Resend and SES and turns
off; the HTML card has the mark, the button once, escaped text and the
site's links; STARTTLS by default; the recovery tests read the MIME
messages.

closes #181, closes #182

Author: Andy McCall @andymccall <[email protected]>
When: 21 days ago · 2026-10-14 10:53 UTC
Signature: ✔ signed by Andy McCall
Hash: cd46e56b1709a01b405ac538ae4092a3fb12b36d6f6847690892fa0f7956aeed
Depends on: 18e381ea88c2 19bb31ff1f5c 34beb1a7e376 3556d08e17f9 93be9ce4653e d23464c0ac60 e8e7158bbc73
Depended on by: 262ec9c51a5c 737de0fac722 a7aa76ac52d7 2bbdc0268c23 b91e2d81b3f1
In bookmarks: api-unknown-fields cancel-landed-runs diffusion-pin-bookmark draft-ready main oh-comment-body-file proposal-list-fast
In tags: v0.5.0 v0.5.1 v0.5.2 v0.6.0 v0.6.1 v0.7.0 v0.8.0 v0.9.0 v0.9.1 v0.9.11 v0.9.15 v0.9.16 v0.9.19 v0.9.2 v0.9.20 v0.9.21 v0.9.22 v0.9.23 v0.9.24 v0.9.3 v0.9.4 v0.9.5 v0.9.6 v0.9.7 v0.9.8 v0.9.9
Edits: 35 atoms, 1 tree operation, 9 files

Browse the tree at this change

hide whitespace changes

added assets/icons/oxygenhub-mail.png +0 −0

No line changes.

modified crates/hub/src/mail.rs +445 −10

modified crates/hub/src/notify/mod.rs +4 −2

modified crates/hub/src/web/admin.rs +58 −5

modified crates/hub/src/web/recovery.rs +4 −2

modified crates/hub/tests/accounts.rs +21 −0

modified crates/hub/tests/recovery.rs +3 −1

modified docs/spec.md +1 −1

modified templates/admin.html +29 −6

		…	73 unchanged lines
74	74
75	75		async fn email(app: &Shared, to: &Account, title: &str, url: &str, actor: &str) {
76	76		let unsubscribe = format!("{}/settings/notifications?unsubscribe={}", app.config.base_url(), to.unsubscribe_key);
77		-	let body = format!("{actor}: {title}\n\n{}{url}\n\nStop these emails: {unsubscribe}\n", app.config.base_url());
78		-	if let Err(e) = crate::mail::send(app, to.name(), &to.email, title, &body).await {
	77	+	let link = format!("{}{url}", app.config.base_url());
	78	+	let body = format!("{actor}: {title}\n\n{link}\n\nStop these emails: {unsubscribe}\n");
	79	+	let action = crate::mail::Action { label: "Open it", url: &link };
	80	+	if let Err(e) = crate::mail::send_letter(app, to.name(), &to.email, title, &body, Some(action), Some(&unsubscribe)).await {
79	81		tracing::warn!("email to {}: {e}", to.email);
80	82		}
81	83		}
		…	11 unchanged lines

		…	26 unchanged lines
27	27		mail_smtp: String,
28	28		mail_from: String,
29	29		mail_enabled: bool,
	30	+	/// The saved mail settings as the panel shows them (oxygenhub#181).
	31	+	mail: crate::mail::Choice,
30	32		my_email: String,
31	33		/// The audit log's next page: rows older than this id (#110).
32	34		audit_older: Option<i64>,
		…	57 unchanged lines
90	92		audit,
91	93		repos,
92	94		notice,
	95	+	mail: crate::mail::describe(&mail.smtp),
93	96		mail_smtp: crate::mail::masked(&mail.smtp),
94	97		mail_from: mail.from.clone(),
95	98		mail_enabled: !mail.smtp.is_empty() && !mail.from.is_empty(),
		…	2 unchanged lines
98	101		}))
99	102		}
100	103
	104	+	impl AdminPage {
	105	+	fn mail_services(&self) -> &'static [(&'static str, &'static str)] {
	106	+	crate::mail::SERVICES
	107	+	}
	108	+	}
	109	+
101	110		#[derive(Deserialize)]
102	111		pub struct MailForm {
103	112		#[serde(rename = "_csrf")]
		…	2 unchanged lines
106	115		smtp: String,
107	116		#[serde(default)]
108	117		from: String,
	118	+	/// The panel's service (oxygenhub#181); absent, `smtp` is the URL as
	119	+	/// before.
	120	+	#[serde(default)]
	121	+	service: String,
	122	+	#[serde(default)]
	123	+	region: String,
	124	+	#[serde(default)]
	125	+	user: String,
	126	+	#[serde(default)]
	127	+	secret: String,
	128	+	#[serde(default)]
	129	+	host: String,
	130	+	#[serde(default)]
	131	+	port: String,
	132	+	#[serde(default)]
	133	+	security: String,
109	134		}
110	135
111	136		/// `POST /admin/mail`: the SMTP URL and From address (#101). The URL
		…	4 unchanged lines
116	141		let me = require_admin(&viewer, &shell)?;
117	142		csrf(&viewer, &f.csrf_token, &shell)?;
118	143		let current = crate::mail::settings(&app);
119		-	let smtp = f.smtp.trim();
120		-	let smtp = if !current.smtp.is_empty() && smtp == crate::mail::masked(&current.smtp) { current.smtp.clone() } else { smtp.to_string() };
	144	+	// A service the panel knows: it makes the SMTP URL (oxygenhub#181).
	145	+	let smtp = match f.service.as_str() {
	146	+	"off" => String::new(),
	147	+	"" \| "url" => {
	148	+	let smtp = f.smtp.trim();
	149	+	if !current.smtp.is_empty() && smtp == crate::mail::masked(&current.smtp) {
	150	+	current.smtp.clone()
	151	+	} else {
	152	+	smtp.to_string()
	153	+	}
	154	+	}
	155	+	_ => {
	156	+	let asked = crate::mail::Asked {
	157	+	service: f.service.clone(),
	158	+	region: f.region.clone(),
	159	+	user: f.user.clone(),
	160	+	secret: f.secret.trim().to_string(),
	161	+	host: f.host.clone(),
	162	+	port: f.port.clone(),
	163	+	security: f.security.clone(),
	164	+	};
	165	+	match crate::mail::compose(&asked, &current.smtp) {
	166	+	Ok(url) => url,
	167	+	Err(why) => return admin_page(&app, shell, Some(why)).await,
	168	+	}
	169	+	}
	170	+	};
121	171		let from = f.from.trim().to_string();
122	172		if !smtp.is_empty() && !(smtp.starts_with("smtp://") \|\| smtp.starts_with("smtps://") \|\| smtp.starts_with("file://")) {
123	173		return admin_page(
		…	4 unchanged lines
128	178		.await;
129	179		}
130	180		if !smtp.is_empty() && from.is_empty() {
131		-	return admin_page(&app, shell, Some("A From address is needed: OxygenHub <hub@example.org>.".into())).await;
	181	+	return admin_page(&app, shell, Some("A From address is needed: OxygenHub <noreply@example.org>.".into())).await;
132	182		}
133	183		crate::mail::save(&app, &smtp, &from).await.map_err(\|e\| Error::from_db(shell.clone(), e))?;
134	184		accounts::audit(&app.db, Some(&me), "admin.mail", if smtp.is_empty() { "off" } else { "on" }, &from).await.ok();
		…	15 unchanged lines
150	200		if me.email.is_empty() {
151	201		return admin_page(&app, shell, Some("Your account has no email address to send the test to.".into())).await;
152	202		}
153		-	let notice = match crate::mail::send(
	203	+	let base = app.config.base_url().to_string();
	204	+	let notice = match crate::mail::send_letter(
154	205		&app,
155	206		me.name(),
156	207		&me.email,
157	208		"Test message",
158		-	"This is a test message from your hub's mail settings. If you can read it, mail works.",
	209	+	"This is a test message from your hub's mail settings. If you can read it, mail works: verification links, password resets and notifications will reach people.",
	210	+	Some(crate::mail::Action { label: "Open the hub", url: &base }),
	211	+	None,
159	212		)
160	213		.await
161	214		{
		…	299 unchanged lines

		…	60 unchanged lines
61	61		account.username,
62	62		app.config.site.name
63	63		);
64		-	crate::mail::send(app, account.name(), &account.email, "Confirm your email address", &body).await
	64	+	let action = crate::mail::Action { label: "Confirm my email address", url: &url };
	65	+	crate::mail::send_letter(app, account.name(), &account.email, "Confirm your email address", &body, Some(action), None).await
65	66		}
66	67
67	68		/// `GET /verify/{secret}`.
		…	53 unchanged lines
121	122		// Sent in the background, so the answer takes as long either way.
122	123		let (mailer, name, addr, user) = (app.clone(), a.name().to_string(), a.email.clone(), a.username.clone());
123	124		tokio::spawn(async move {
124		-	if let Err(err) = crate::mail::send(&mailer, &name, &addr, "Reset your password", &body).await {
	125	+	let action = crate::mail::Action { label: "Choose a new password", url: &url };
	126	+	if let Err(err) = crate::mail::send_letter(&mailer, &name, &addr, "Reset your password", &body, Some(action), None).await {
125	127		tracing::warn!("reset mail for {user}: {err}");
126	128		}
127	129		});
		…	74 unchanged lines

		…	630 unchanged lines
631	631		// Not for everyone.
632	632		let r = post(app, "/admin/mail", None, &format!("_csrf={csrf}&smtp=&from=")).await;
633	633		assert_ne!(r.status, StatusCode::OK);
	634	+
	635	+	// The service panel (oxygenhub#181): Resend asks only for its key,
	636	+	// which is never shown again and is kept when left empty.
	637	+	let from = "from=OxygenHub+%3Cnoreply%40example.org%3E";
	638	+	let r = post(app, "/admin/mail", Some(&andy), &format!("_csrf={csrf}&service=resend&secret=&{from}")).await;
	639	+	assert!(r.body.contains("Give the Resend API key"), "{}", r.body);
	640	+	let r = post(app, "/admin/mail", Some(&andy), &format!("_csrf={csrf}&service=resend&secret=re_test_key_1&{from}")).await;
	641	+	assert!(r.body.contains("Mail settings saved") && !r.body.contains("re_test_key_1"), "{}", r.body);
	642	+	assert!(r.body.contains(r#"<option value="resend" selected>"#) && r.body.contains("saved: leave empty to keep it"), "{}", r.body);
	643	+	assert_eq!(oxygenhub::mail::settings(app).smtp, "smtps://resend:[email protected]:465");
	644	+	let r = post(app, "/admin/mail", Some(&andy), &format!("_csrf={csrf}&service=resend&secret=&{from}")).await;
	645	+	assert!(r.body.contains("Mail settings saved"), "{}", r.body);
	646	+	assert_eq!(oxygenhub::mail::settings(app).smtp, "smtps://resend:[email protected]:465", "kept");
	647	+	// Amazon SES in London, then off.
	648	+	let r =
	649	+	post(app, "/admin/mail", Some(&andy), &format!("_csrf={csrf}&service=ses&region=eu-west-2&user=AKIAEXAMPLE&secret=s3cret&{from}"))
	650	+	.await;
	651	+	assert!(r.body.contains(r#"<option value="ses" selected>"#), "{}", r.body);
	652	+	assert_eq!(oxygenhub::mail::settings(app).smtp, "smtps://AKIAEXAMPLE:[email protected]:465");
	653	+	let r = post(app, "/admin/mail", Some(&andy), &format!("_csrf={csrf}&service=off&{from}")).await;
	654	+	assert!(r.body.contains("Mail is off"), "{}", r.body);
634	655		}
635	656
636	657		/// A stand-in chat-completions endpoint: answers "OK from mock" and keeps
		…	369 unchanged lines

		…	82 unchanged lines
83	83		}
84	84
85	85		/// Every message so far, oldest first, as text.
	86	+	/// Each message written to `dir`, as a reader sees it: MIME's
	87	+	/// quoted-printable soft breaks joined and `=3D` decoded (#182).
86	88		fn mail(dir: &Path) -> Vec<String> {
87	89		let mut names: Vec<_> = std::fs::read_dir(dir).unwrap().flatten().map(\|e\| e.path()).collect();
88	90		names.sort();
89		-	names.iter().map(\|p\| std::fs::read_to_string(p).unwrap()).collect()
	91	+	names.iter().map(\|p\| std::fs::read_to_string(p).unwrap().replace("=\r\n", "").replace("=\n", "").replace("=3D", "=")).collect()
90	92		}
91	93
92	94		/// Mail is sent in the background for resets; wait for `n` messages.
		…	129 unchanged lines

		…	173 unchanged lines
174	174		- Reset by email. `/login/reset` takes a username or a verified email. When it matches an active account with a verified email and the hub can send mail, a link valid for one hour goes to that address, at most one every two minutes per account. The page answers the same way whether or not anything matched, so it cannot be used to find accounts.
175	175		- Reset by an administrator. When the hub cannot send mail, or the account has no verified email, an administrator issues a reset link from the admin page (valid 24 hours), shown once to hand over by other means. The audit log records who issued it.
176	176		- Using a reset link sets a new password (the same rules as registration), rotates the session salt so every existing session ends, voids the account's other reset links, and records `password.reset` in the audit log. It does not turn off TOTP: a reset account with two-factor sign-in still needs its code. A banned account cannot be reset.
177		-	- Mail. `[email] smtp` is an `smtp://` or `smtps://` URL, or `file:///path` for development, which writes each message to that directory as a file instead of sending it. Administration has a Mail form (#101) whose SMTP URL and From address, once saved, override `[email]`; the password is shown masked, an empty URL turns mail off, and a button sends a test message to the administrator's own address.
	177	+	- Mail. `[email] smtp` is an `smtp://` or `smtps://` URL, or `file:///path` for development, which writes each message to that directory as a file instead of sending it. Administration has a Mail panel (#101, #181) whose settings, once saved, override `[email]`: pick a service and give only what it needs (Resend: its API key; Amazon SES: the region and SES SMTP credentials; Mailgun: `us` or `eu` and the SMTP login; another SMTP server: server, port, security, user and password; or an SMTP URL, for anything else and `file://`), and the panel stores one standard SMTP URL, so every service is SMTP underneath and any provider works. Keys and passwords are never shown again; left empty, the saved one stays while the service, server and user do. An `smtp://` URL that says nothing of TLS requires STARTTLS (`?tls=opportunistic` or `?tls=none` say otherwise; a relay on this machine needs none). Off turns mail off, and a button sends a test message to the administrator's own address. Every message goes as plain text and as HTML in the site's look (#182): the Oxygen band with the mark, sent inline so it shows without loading anything, the subject as heading, the body with its links, the message's action as a button with its link beneath, and a footer of the site's links (Explore, Help, Notification settings, and Stop these emails on notifications).
178	178
179	179		### 5.2 Organisations and teams
180	180
		…	536 unchanged lines

		…	69 unchanged lines
70	70		</section>
71	71		<section class="panel" id="mail">
72	72		<h2>Mail</h2>
73		-	<form class="card" method="post" action="/admin/mail">
	73	+	<form class="card mail-panel" method="post" action="/admin/mail">
74	74		<input type="hidden" name="_csrf" value="{{ shell.csrf }}">
75		-	<label for="smtp">SMTP URL</label>
76		-	<input type="text" id="smtp" name="smtp" value="{{ mail_smtp }}" placeholder="smtps://user:[email protected]:465">
77		-	<label for="mailfrom">From</label>
78		-	<input type="text" id="mailfrom" name="from" value="{{ mail_from }}" placeholder="OxygenHub <[email protected]>">
	75	+	<label for="mailservice">Service</label>
	76	+	<select id="mailservice" name="service" data-mail-service>{% for (v, label) in mail_services() %}<option value="{{ v }}"{% if mail.service == *v %} selected{% endif %}>{{ label }}</option>{% endfor %}</select>
	77	+	<p class="small mute" data-for="resend">Resend sends through <code>smtp.resend.com</code>; the login is <code>resend</code> and the password your API key. Verify your domain in Resend first.</p>
	78	+	<p class="small mute" data-for="ses">Amazon SES: the region your identity is verified in, and the SMTP credentials from SES › SMTP settings (not an AWS access key).</p>
	79	+	<p class="small mute" data-for="mailgun">Mailgun: <code>us</code> or <code>eu</code>, and the domain's SMTP login and password.</p>
	80	+	<div data-for="ses mailgun"><label for="mailregion">Region</label><input type="text" id="mailregion" name="region" value="{{ mail.region }}" placeholder="eu-west-2 for SES; us or eu for Mailgun"></div>
	81	+	<div data-for="smtp"><label for="mailhost">Server</label><input type="text" id="mailhost" name="host" value="{{ mail.host }}" placeholder="mail.example.org">
	82	+	<label for="mailport">Port</label><input type="text" id="mailport" name="port" value="{{ mail.port }}" placeholder="587">
	83	+	<label for="mailsecurity">Security</label><select id="mailsecurity" name="security"><option value="starttls"{% if mail.security == "starttls" %} selected{% endif %}>STARTTLS (usually port 587)</option><option value="tls"{% if mail.security == "tls" %} selected{% endif %}>TLS from the start (usually port 465)</option><option value="none"{% if mail.security == "none" %} selected{% endif %}>None (a relay on this machine)</option></select></div>
	84	+	<div data-for="ses mailgun smtp"><label for="mailuser">User name</label><input type="text" id="mailuser" name="user" value="{% if mail.service != "resend" %}{{ mail.user }}{% endif %}" autocomplete="off"></div>
	85	+	<div data-for="resend ses mailgun smtp"><label for="mailsecret">{% if mail.service == "resend" %}API key{% else %}Password or API key{% endif %}</label><input type="password" id="mailsecret" name="secret" value="" autocomplete="new-password" placeholder="{% if mail.has_secret %}saved: leave empty to keep it{% else %}{% endif %}"></div>
	86	+	<div data-for="url"><label for="smtp">SMTP URL</label><input type="text" id="smtp" name="smtp" value="{{ mail_smtp }}" placeholder="smtps://user:[email protected]:465"></div>
	87	+	<div data-for="resend ses mailgun smtp url"><label for="mailfrom">From</label><input type="text" id="mailfrom" name="from" value="{{ mail_from }}" placeholder="OxygenHub <[email protected]>"></div>
79	88		<button type="submit">SAVE</button>
80	89		</form>
	90	+	<script>
	91	+	/* Mail panel (oxygenhub#181): show the fields the chosen service asks. */
	92	+	(function () {
	93	+	var sel = document.querySelector("[data-mail-service]");
	94	+	if (!sel) return;
	95	+	var show = function () {
	96	+	document.querySelectorAll(".mail-panel [data-for]").forEach(function (el) {
	97	+	el.hidden = el.getAttribute("data-for").split(" ").indexOf(sel.value) < 0;
	98	+	});
	99	+	};
	100	+	sel.addEventListener("change", show);
	101	+	show();
	102	+	})();
	103	+	</script>
81	104		<form class="card" method="post" action="/admin/mail/test"><input type="hidden" name="_csrf" value="{{ shell.csrf }}"><button type="submit"{% if !mail_enabled \|\| my_email.is_empty() %} disabled{% endif %}>SEND A TEST{% if !my_email.is_empty() %} TO {{ my_email }}{% endif %}</button></form>
82		-	<p class="small mute">{% if mail_enabled %}Mail is on: verification and reset links go by email.{% else %}Mail is off: verification and reset links are issued by hand.{% endif %} An empty URL turns it off. The password stays on the server and is shown masked.</p>
	105	+	<p class="small mute">{% if mail_enabled %}Mail is on: verification and reset links go by email.{% else %}Mail is off: verification and reset links are issued by hand.{% endif %} Off turns it off. Passwords and keys stay on the server and are never shown again. Every service is SMTP underneath, so any provider works: <code>smtps://USER:PASSWORD@HOST:465</code> for TLS from the start, or <code>smtp://USER:PASSWORD@HOST:587</code>, which the hub sends with STARTTLS required (add <code>?tls=opportunistic</code> or <code>?tls=none</code> to say otherwise; a relay on this machine needs none).</p>
83	106		</section>
84	107		{% call va::panel("/admin", variables, shell.csrf, "Every repository's jobs get these, unless an organisation or repository sets the same name.") %}
85	108		{% call se::panel("/admin", secrets, shell.csrf, "Every repository's jobs may use these, unless an organisation or repository sets the same name.") %}
		…	11 unchanged lines

`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet

		…	47 unchanged lines
48	48		!cfg.smtp.is_empty() && !cfg.from.is_empty()
49	49		}
50	50
51		-	/// Send a plain-text message. The subject gets the site's name in brackets.
	51	+	/// The one thing a message asks of its reader, shown as its button.
	52	+	#[derive(Clone, Copy, Debug)]
	53	+	pub struct Action<'a> {
	54	+	pub label: &'a str,
	55	+	pub url: &'a str,
	56	+	}
	57	+
	58	+	/// Send a message with no button. The subject gets the site's name in
	59	+	/// brackets.
52	60		pub async fn send(app: &Shared, to_name: &str, to_addr: &str, subject: &str, body: &str) -> Result<(), String> {
	61	+	send_letter(app, to_name, to_addr, subject, body, None, None).await
	62	+	}
	63	+
	64	+	/// Send a message as plain text and as HTML in the site's look
	65	+	/// (oxygenhub#182): the Oxygen mark, `action` as a button, and the site's
	66	+	/// links (with `unsubscribe`, when given) in the footer. The text part is
	67	+	/// `body` as written.
	68	+	pub async fn send_letter(
	69	+	app: &Shared,
	70	+	to_name: &str,
	71	+	to_addr: &str,
	72	+	subject: &str,
	73	+	body: &str,
	74	+	action: Option<Action<'_>>,
	75	+	unsubscribe: Option<&str>,
	76	+	) -> Result<(), String> {
53	77		if !enabled(app) {
54	78		return Err("this hub does not send mail".into());
55	79		}
56	80		let cfg = settings(app);
57		-	let subject = format!("[{}] {subject}", app.config.site.name);
58		-	if let Some(dir) = cfg.smtp.strip_prefix("file://") {
59		-	let name = format!("{}-{}.eml", crate::db::now_ms(), crate::auth::random_hex(4));
60		-	let text = format!("From: {}\nTo: {to_name} <{to_addr}>\nSubject: {subject}\n\n{body}", cfg.from);
61		-	return tokio::fs::write(std::path::Path::new(dir).join(name), text).await.map_err(\|e\| format!("write mail to {dir}: {e}"));

Mail: a service panel, and email that looks like OxygenHub cd46e56b1709

Keyboard