Guided setup: how this server sends mail

jcoffey-dev commented

2026-09-28 17:56:59 +00:00

Owner

First guided setup from the settings-reorg spec. Built on #34 (Settings menu and Overview): merge that first, and this diff shrinks to its own commit (f23851a).

Offered from Settings › Overview, Delivery strategy and Routes. It asks "Guided or manual?" each time.

How mail leaves. An optional port 25 check runs the Delivery tests probe from this server against a big mail domain (MX lookup, connection, greeting; nothing is sent). "Recommended" follows the result: direct when a server answers, relay when it's blocked.
Relay service. Presets: Amazon SES (by region), Mailgun (US/EU), SendGrid, Postmark, Brevo, SMTP2GO, or any other server. Each says where its SMTP credentials are and what to verify at the service first. Implicit TLS on 465 wherever the service offers it.
Sign-in. The password is typed here, saved as the route's secret, and never shown again. Running the guide again with the field left empty keeps the saved one.
Review. Every change in plain words before anything is written:
- a Relay route named relay;
- the route expression's fallback pointed at it. is_local_domain → 'local' and any other rules are left as they are;
- for a STARTTLS relay (Postmark, or any server on 587), a relay-tls TLS strategy with STARTTLS required, and a first rule mx == '<relay host>' → 'relay-tls'. STARTTLS is otherwise only attempted, so the relay password could go out unencrypted.
Test it. Send from webmail, watch Outbound delivery, check the queue's last error.

Writes happen one at a time. If a later one is refused, what this run added or changed is put back. Switching back to direct restores the 'mx' fallback and drops the relay TLS rule; the relay route stays saved but unused.

Checked: 11 unit tests for the planner and the port 25 verdict (441 total), plus typecheck, lint and build. In Chrome against a local server:

The port check on this laptop came back blocked, and the relay option was marked Recommended.
The Postmark path wrote exactly the route, the relay-tls strategy and the rules above. Read back over JMAP, with no config warnings.
Running the guide again and choosing direct restored the stock route and tls expressions exactly.

The provider hosts and ports are from each service's docs as I know them. Worth a spot-check before release.

English only: about 50 new UI strings, plus the presets' hints (7 services × 3) and 7 change sentences.

First guided setup from the settings-reorg spec. **Built on #34** (Settings menu and Overview): merge that first, and this diff shrinks to its own commit (`f23851a`). Offered from Settings › Overview, Delivery strategy and Routes. It asks "Guided or manual?" each time. 1. **How mail leaves.** An optional port 25 check runs the Delivery tests probe from this server against a big mail domain (MX lookup, connection, greeting; nothing is sent). "Recommended" follows the result: direct when a server answers, relay when it's blocked. 2. **Relay service.** Presets: Amazon SES (by region), Mailgun (US/EU), SendGrid, Postmark, Brevo, SMTP2GO, or any other server. Each says where its SMTP credentials are and what to verify at the service first. Implicit TLS on 465 wherever the service offers it. 3. **Sign-in.** The password is typed here, saved as the route's secret, and never shown again. Running the guide again with the field left empty keeps the saved one. 4. **Review.** Every change in plain words before anything is written: - a Relay route named `relay`; - the route expression's fallback pointed at it. `is_local_domain` → `'local'` and any other rules are left as they are; - for a STARTTLS relay (Postmark, or any server on 587), a `relay-tls` TLS strategy with STARTTLS **required**, and a first rule `mx == '<relay host>'` → `'relay-tls'`. STARTTLS is otherwise only attempted, so the relay password could go out unencrypted. 5. **Test it.** Send from webmail, watch Outbound delivery, check the queue's last error. Writes happen one at a time. If a later one is refused, what this run added or changed is put back. Switching back to direct restores the `'mx'` fallback and drops the relay TLS rule; the relay route stays saved but unused. **Checked:** 11 unit tests for the planner and the port 25 verdict (441 total), plus typecheck, lint and build. In Chrome against a local server: - The port check on this laptop came back blocked, and the relay option was marked Recommended. - The Postmark path wrote exactly the route, the `relay-tls` strategy and the rules above. Read back over JMAP, with no config warnings. - Running the guide again and choosing direct restored the stock `route` and `tls` expressions exactly. The provider hosts and ports are from each service's docs as I know them. Worth a spot-check before release. English only: about 50 new UI strings, plus the presets' hints (7 services × 3) and 7 change sentences.

jcoffey-dev referenced this pull request

2026-09-28 19:14:15 +00:00

Guided setup: certificates, automatically #39

jcoffey-dev added 3 commits 2026-09-28 19:32:08 +00:00

Settings in nine task-based groups on the top bar, with an Overview page 10527002e0

The server's Settings menu is nineteen groups, too many for the section
bar, so Settings was the one section left on the sidebar. The admin now
regroups the same 107 pages by job: Mail flow, Spam filter, Security,
Network, Mail & apps, Storage, Monitoring and System, with plainer labels
and protocol-level MTA pages in a dimmed Advanced group. View names and
URLs are unchanged, and a page the table doesn't know lands in
System › Other.

Settings › Overview is the new landing page: a card per category, the
guided setups, and the pages whose values differ from their defaults.

Overview cards explain the menu bar rather than link into it

ci / build (pull_request) Successful in 1m19s

Details

ci / publish (pull_request) Skipped

Details

d0c2f0f370

Each category card is now its name and what it covers, with no links and
no page count: the bar above does the navigating.

Guided setup: how this server sends mail

ci / build (pull_request) Successful in 1m29s

Details

ci / publish (pull_request) Skipped

Details

57b44cae27

Settings › Overview, Delivery strategy and Routes offer a guide ("Guided
or manual?" each time) that:

- checks port 25 from this server with the Delivery tests probe (MX
  lookup, connection, greeting; nothing is sent) and recommends direct
  delivery or a relay from the result;
- sets up a relay from presets: Amazon SES (by region), Mailgun (US/EU),
  SendGrid, Postmark, Brevo, SMTP2GO or any other server, with where to
  find each one's SMTP credentials and what to verify first;
- shows every change in plain words before writing it: a Relay route
  named relay, the route fallback pointed at it (local delivery and any
  other rules untouched), and, for a STARTTLS relay, a relay-tls strategy
  with STARTTLS required for that host, so the password never goes out
  unencrypted. Implicit TLS on 465 wherever the service offers it;
- writes it step by step and puts back what it wrote if a later step is
  refused;
- ends with how to test it: send from webmail, watch Outbound delivery
  and the queue.

Running it again edits the saved relay (an empty password keeps the
saved one), or switches back to direct delivery, which also drops the
relay's TLS rule.

jcoffey-dev force-pushed feature/sending-setup from f23851aa29 to 57b44cae27

2026-09-28 19:32:08 +00:00

Compare

jcoffey-dev merged commit 4236bd000d into main

2026-09-28 21:52:53 +00:00

jcoffey-dev deleted branch feature/sending-setup

2026-09-28 21:52:53 +00:00

Guided setup: how this server sends mail #36