docs(cloud): Bring Your Own Mail Server guide for organization administrators - #1235
Merged
Conversation
Adds a dedicated guide for an Organization Administrator configuring their organization's own outbound mail server on the Email tab of Edit Organization, and a short anchored section on the Organization Management page at the anchor the product's "Learn more" links target. Every product claim was verified against meshery-cloud master plus the fm/mc-org-smtp-routing-leg branch and the organization_smtp contract in meshery/schemas, and against Google's current help pages for the Workspace paths. The connection test is described as the probe it is, domain verification with all three failure outcomes, fallback with the "(via Layer5)" rewrite, and a troubleshooting table keyed on the exact strings the tab shows. AGENTS.md records that the Cloud UI hardcodes the org-management anchor. Signed-off-by: Mia Grenell <184569369+miacycle@users.noreply.github.com>
… the guide from white-labeling The Gmail SMTP server paragraph now says plainly that Google's pages do not state the From rewrite and presents it as what happens in practice, with the relay service recommended for a white-labelled sender because it has no such constraint. The white-labeling page gains one paragraph pointing to the guide, since a fully branded email still arrives from a Layer5 address until an organization configures its own mail server. It states when custom delivery actually becomes active. Signed-off-by: Mia Grenell <184569369+miacycle@users.noreply.github.com>
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Advanced Run ID: 📒 Files selected for processing (4)
📝 WalkthroughWalkthroughThe documentation adds a Bring Your Own Mail Server guide. It covers SMTP configuration, DNS verification, connection testing, delivery health, fallback behavior, provider-specific setup, troubleshooting, and related organization-management references. ChangesCustom Mail Server Documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Suggested reviewers: ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
|
🚀 Preview deployment: https://docs.layer5.io/pr-preview/pr-1235/
|
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
The changes are documentation-only and coherent, with only minor fixable nits identified (spelling and a self-link that can be made more robust).
Pull request overview
Adds a new Layer5 Cloud documentation guide for Organization Administrators to configure a per-organization outbound SMTP server (“Bring Your Own Mail Server”), and wires it into existing Organization Management and white-labeling docs (plus a note in AGENTS.md about an externally hardcoded anchor).
Changes:
- Added a new BYO SMTP guide page covering setup, domain verification, connection testing, status/health interpretation, fallback behavior, Google Workspace options, and troubleshooting.
- Updated the Organization Management guide to mention the Email tab and added a short anchored section (
#configuring-your-own-mail-server) that points to the full guide. - Added a cross-link from the white-labeling guide and recorded the anchor dependency in
AGENTS.md.
File summaries
| File | Description |
|---|---|
| content/en/cloud/guides/organizations/org-management/bring-your-own-mail-server.md | New end-to-end BYO SMTP guide for org admins (setup, verification, testing, operations, troubleshooting). |
| content/en/cloud/guides/organizations/org-management/_index.md | Adds Email tab to the Edit Organization overview and introduces the anchored entrypoint section that links to the new guide. |
| content/en/cloud/guides/self-hosted/white-labeling/_index.md | Cross-links white-labeling email branding to the BYO SMTP guide and clarifies when mail originates from the org’s domain. |
| AGENTS.md | Documents the external dependency on the #configuring-your-own-mail-server anchor. |
Review details
- Files reviewed: 4/4 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| - **SMTP Host**: your server's hostname. | ||
| - **Port (587 for STARTTLS, 465 for TLS)**: the submission port. The port and the encryption mode must agree. | ||
| - **Encryption**: `starttls`, `tls` or `none`. | ||
| - **Authentication (None only for a relay that authorises by IP)**: `plain`, `cram-md5` or `none`. Any method other than `none` requires both a username and a password. |
| Understand exactly what the test does. It opens a connection to your server, negotiates the encryption mode you chose, greets the server, presents your username and password, and hangs up. It verifies that the server accepts the connection and the credentials. **It does not deliver a message**, even though the field asks for an address, and no message arrives anywhere. On success the tab reports "Test message delivered." Read that as "the connection and credentials were accepted": the API's own result for the same outcome is "The mail server accepted the connection and the credentials. No test message was sent." | ||
|
|
||
| {{< alert title="What a passing test does not prove" type="warning" >}} | ||
| Because the test hangs up before naming a sender or a recipient, it cannot detect a server that accepts your credentials but refuses to send as your from address. Google's Gmail SMTP server is the common case: in practice it accepts the login and then sends from the signed-in account's address instead. A passing test followed by mail arriving from the wrong address is that situation, and the fix is on the provider's side. See [Google Workspace](/cloud/guides/organizations/org-management/bring-your-own-mail-server/#google-workspace). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds the user-facing guide for an Organization Administrator configuring their organization's own outbound mail server (BYO SMTP) in Layer5 Cloud.
Do not merge until both of these have shipped
layer5io/meshery-cloudbranchfm/mc-org-smtp-routing-legand ships in v1.0.253. On the current release (v1.0.252) mail still leaves through the shared relay whatever the Email tab shows. Releases: https://github.com/layer5io/meshery-cloud/releasesThis guide is written to the behaviour after both land, with no provisional markers in the text. The sections that depend on #6064's exact outcome, and that need a targeted re-verification before merge, are:
What is added
content/en/cloud/guides/organizations/org-management/bring-your-own-mail-server.md- the guide (new page, weight 3, beside Navigating Organizations). Covers what the feature does, prerequisites, the mail-server requirements the product enforces, configuring on the Email tab, proving the domain with the DNS TXT record and all three verification outcomes, what the connection test does and does not prove, turning the server on, reading delivery health, fallback and the "(via Layer5)" rewrite, changing settings, rotating the password, turning off and removing, a Google Workspace section with both supported paths, and a troubleshooting table keyed on the exact strings the tab shows.content/en/cloud/guides/organizations/org-management/_index.md- adds the Email tab to the Edit Organization list and a short section at the anchor#configuring-your-own-mail-server, which is the URL every "Learn more" link on the Email tab hardcodes (MAIL_DOCS_URLinorg-smtp-tab.tsx). The section points to the full guide.content/en/cloud/guides/self-hosted/white-labeling/_index.md- one paragraph under Contact Information in Email Notifications pointing to the guide, since a fully branded email still arrives from a Layer5 address until a mail server is configured.AGENTS.md- records that anchor dependency for future editors.How every claim was verified
Read-only against
meshery-cloudmaster (post #6063) andorigin/fm/mc-org-smtp-routing-leg, theorganization_smtpcontract inmeshery/schemas, and the Email tab source. In particular:organization_smtp_prober.go): connect, encryption, greeting, AUTH, QUIT. NoMAIL FROM, no message. The guide says exactly that, and notes the tab's "Test message delivered." wording (layer5io/meshery-cloud#6065)._meshery-mail.<domain>, valuemeshery-mail-verification=<token>, three outcomes fromorganization_smtp_domain_resolver.go. Thecustom-domainshortcut in the contract is never produced by the code, so it is not documented.mail_route.goon the routing branch. No circuit exists (#6057), so "Failing" is documented as "the last attempt failed" and not as "dialling stopped".mail_transport.go; address screen ininternal_address_guard.go; the allowlist is applied at test time, not at save, and the guide says so.smtp.gmail.comrewrites an unregistered From address; the guide says so explicitly and presents it as observed behaviour, with Google's "Send mail as" page linked for the remedy and the relay service recommended for a white-labelled sender because it has no such constraint.What still blocks
Found while verifying, filed in meshery-cloud:
verified/unverified/failingstatus vocabulary (#6054), the tab keys on the contract vocabulary, so the chip always reads "Not yet proven" and the "Turn on" button never renders. The routing leg readsmetadata.enabled, which only that button sets. Until it is fixed, "Turning the Server On" and "Reading the status" in this guide describe the intended behaviour, not the staged one.Supersedes #1232
#1232 adds a shorter section on the same page. This PR supersedes it. The claims there that are false against the code, and where this text differs:
organization_smtp_prober.go), and routing starts when the server is turned on, not on a test. This guide says both.custom-domainmethod; every domain needs the TXT record. Not documented here.Salvaged from #1232: the white-labeling page cross-link, rewritten to state when custom delivery actually becomes active (verified domain, passed test, turned on, subject to fallback), which is the qualification CodeRabbit asked for there. The alert #1232 added to the self-hosted SMTP troubleshooting guide is not carried; that guide is for a different audience and the brief asks not to extend it.
Test plan
npm installthenPATH="$PWD/node_modules/.bin:$PATH" hugo -d <outdir>builds cleanly.org-management/index.htmlcarriesid="configuring-your-own-mail-server"and links to the new page./#prefix that relative links inside alert shortcodes produce.Summary by CodeRabbit