From 06d97c77b535b55b163059e0c9ae82430f65ca2b Mon Sep 17 00:00:00 2001 From: James <160366376+hortison@users.noreply.github.com> Date: Tue, 8 Sep 2026 11:08:51 -0500 Subject: [PATCH 1/3] docs(cloud): worked SMTP examples per provider, and re-verify the page against v1.0.253 The Bring Your Own Mail Server guide covered Google Workspace well and left every other Provider preset as a bare name in a list. Adds a worked example for each of them, and corrects the product claims that were written before the derived-status and connection-test changes shipped. New sections, each with the exact field values to type and the gotchas that otherwise become support tickets, sourced from the provider's current docs: - Microsoft 365: SMTP AUTH off by default since Jan 2020, PLAIN-only on our side, Send As for a different from address, security defaults, the basic-auth retirement timeline, and why HVE and the MX relay do not substitute. - Amazon SES: the preset's region is a placeholder, SMTP credentials are not AWS access keys and are per-region, the sandbox refuses unverified recipients, and 2587/2465 are outside our port allowlist. - SendGrid: the username is the literal string apikey. - Postmark: the Server API token is both username and password, the from address needs a Sender Signature or verified domain, and there is no implicit-TLS port. - Any Other Provider: the four requirements to ask any provider for. Also answers, in place, Google's "you must use OAuth" paragraph that readers hit before our app-password instruction: app passwords are Google's stated exception, and Layer5 Cloud has no XOAUTH2 support today. Corrections against meshery-cloud master: - The status chips are Off / Delivering / Failing / Not yet proven. "Turned off" did not exist, and Off also means never turned on. Not yet proven routes mail through the organization's server rather than the shared one. - There is no stop-dialling circuit; Failing describes the last attempt only. - The control is "Test connection", it sends no message and takes no recipient, and the success string is "The mail server accepted the connection and the credentials. No test message was sent." The old "Test message delivered." string was corrected in v1.0.253. - Fallback covers a server that does not accept a message - down, timed out, TLS or auth - not only one that refuses. Adds the unacknowledged end-of-DATA case, which is never re-sent under either setting. - A non-allowlisted port reports as a blocked target, not as an invalid transport. - Save, turn-on, turn-off and removal confirmations, the enablement hints, the Last success field name, and the counter's meaning now match the screen. Feature is available as of Layer5 Cloud v1.0.253. The page itself landed in #1235. Signed-off-by: James <160366376+hortison@users.noreply.github.com> --- AGENTS.md | 11 ++ .../organizations/org-management/_index.md | 4 +- .../bring-your-own-mail-server.md | 176 +++++++++++++++--- 3 files changed, 163 insertions(+), 28 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0c03060f8c5..e9fd1126b7e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,6 +44,17 @@ A literal backslash inside inline HTML is a related trap: Goldmark reads the `\< (`content/en/kanvas/reference/keyboard-shortcuts.md` is the worked example) and confirm the built HTML, not the source, before committing. +## Documenting Layer5 Cloud behaviour + +The cloud guides describe a product that lives in `meshery-cloud`, so every product claim is +verified against `origin/master` there, never against a summary. The screen strings are in +`ui/components/identity/org-management/`; the behaviour behind them is in `server/handlers/`. + +That repo's own `docs/reference/` and `docs/runbooks/` are the best starting point but are not +the arbiter - they have described behaviour the handlers do not implement. Confirm a capability +has a producer in the Go or TSX before writing it up: a contract enum member or a runbook +sentence is not proof the feature ships. + ## Maintaining this file Keep this file for knowledge useful to almost every future agent session in this project. diff --git a/content/en/cloud/guides/organizations/org-management/_index.md b/content/en/cloud/guides/organizations/org-management/_index.md index 7358971f6f4..501feed7cb4 100644 --- a/content/en/cloud/guides/organizations/org-management/_index.md +++ b/content/en/cloud/guides/organizations/org-management/_index.md @@ -77,9 +77,9 @@ Switching identity providers does not affect existing user accounts or login his The **Email** tab lets your Organization send application mail such as invitations and notifications through **its own SMTP server**, from **its own domain**, instead of through Layer5's shared mail server. Nothing about the message then points to a shared provider. -Setting it up has three steps, and mail keeps leaving through Layer5's shared server until all three are done: register the server and its credentials, prove control of the sending domain by publishing a DNS TXT record, and pass a connection test before turning the server on. The tab reports delivery health afterwards, and a fallback setting decides what happens to a message your server refuses. +Setting it up has three steps, and mail keeps leaving through Layer5's shared server until all three are done: register the server and its credentials, prove control of the sending domain by publishing a DNS TXT record, and pass a connection test before turning the server on. The tab reports delivery health afterwards, and a fallback setting decides what happens to a message your server does not accept. -The full walkthrough, including the Google Workspace paths and a troubleshooting table for every failure the tab reports, is in [Bring Your Own Mail Server](bring-your-own-mail-server/). +The full walkthrough, including a worked example for Google Workspace, Microsoft 365, Amazon SES, SendGrid and Postmark, and a troubleshooting table for every failure the tab reports, is in [Bring Your Own Mail Server](bring-your-own-mail-server/). {{< alert title="Who can configure this" type="info" >}} Organization Administrators and Owners can configure, test, turn on, turn off, and remove their Organization's mail server, under the same gate as the Identity Providers tab. diff --git a/content/en/cloud/guides/organizations/org-management/bring-your-own-mail-server.md b/content/en/cloud/guides/organizations/org-management/bring-your-own-mail-server.md index 180f8cc41e3..07328b7cc61 100644 --- a/content/en/cloud/guides/organizations/org-management/bring-your-own-mail-server.md +++ b/content/en/cloud/guides/organizations/org-management/bring-your-own-mail-server.md @@ -11,7 +11,7 @@ By default, every email Layer5 Cloud sends to the members of your Organization l The **Email** tab of Edit Organization changes that. Your Organization registers its own SMTP server and its own from address, and once you have proven control of the sending domain and turned the server on, application mail such as invitations and notifications leaves through your server from your domain. Nothing about the message points to a shared provider. -This guide walks an Organization Administrator through configuring it, proving the domain, testing the connection, and reading the delivery health it reports afterwards. +This guide walks an Organization Administrator through configuring it, proving the domain, testing the connection, and reading the delivery health it reports afterwards. It then gives a worked example for each provider the tab offers a preset for: [Google Workspace](#google-workspace), [Microsoft 365](#microsoft-365), [Amazon SES](#amazon-ses), [SendGrid](#sendgrid), [Postmark](#postmark), and [any other provider](#any-other-provider). {{< alert title="Who can configure this" type="info" >}} Organization Administrators and Owners can configure, test, turn on, turn off, and remove their Organization's mail server. The same gate applies to the [Identity Providers tab](/cloud/guides/organizations/org-management/#configuring-identity-providers-bring-your-own-credentials). @@ -22,7 +22,7 @@ Organization Administrators and Owners can configure, test, turn on, turn off, a Have these in hand before you open the Email tab: - **The hostname and submission port of your SMTP server**, and whether it uses STARTTLS or implicit TLS. -- **A username and password the server accepts.** For hosted providers this is an app password or a dedicated SMTP credential, not the password you sign in with. See [Google Workspace](#google-workspace) below for the two paths Google supports. +- **A username and password the server accepts.** For hosted providers this is an app password or a dedicated SMTP credential, not the password you sign in with. Each provider mints it somewhere different: see [Google Workspace](#google-workspace), [Microsoft 365](#microsoft-365), [Amazon SES](#amazon-ses), [SendGrid](#sendgrid) and [Postmark](#postmark) below. - **A from address on a domain whose DNS you control.** You prove control by publishing a TXT record, so you need access to the domain's DNS zone. ### Requirements on the mail server @@ -53,13 +53,13 @@ Layer5 Cloud refuses a configuration that does not meet these, so check them fir - **Fall back to the shared mail server when delivery fails**: on by default. See [Fallback](#fallback) before you turn it off. 5. Click **Save mail server**. -The tab confirms with "Saved your Organization's mail server. Verify the from domain to start routing mail through it." Nothing about your email has changed yet. Mail keeps leaving through Layer5's shared server until you have verified the domain, passed a connection test, and turned the server on. +The tab confirms with "Saved *your Organization's name*'s mail server. Test the connection, verify the from domain, then turn it on to start routing mail through it." Nothing about your email has changed yet. Mail keeps leaving through Layer5's shared server until you have verified the domain, passed a connection test, and turned the server on. -Once saved, the tab switches to its configured view. The heading reads "Your Organization is using its own mail server" beside a status chip, followed by the panels **Delivery health**, **From-domain verification**, **Mail server settings**, **Password** and **Stop using your own mail server**. +Once saved, the tab switches to its configured view. The heading names your Organization and states where its mail is going: it reads "*Your Organization* has its own mail server set up." while the server is off, and "*Your Organization* is using its own mail server." once it is on. A status chip sits beside it, followed by the panels **Delivery health**, **From-domain verification**, **Mail server settings**, **Password** and **Stop using your own mail server**. ## Proving You Control the Sending Domain -Layer5 Cloud will not send as a domain you have not proven you control. The proof is a DNS TXT record. +The Email tab will not let you turn a server on until you have proven you control the domain in its from address. The proof is a DNS TXT record, and every from domain needs one. The **From-domain verification** panel names the domain taken from your from address, shows a **Not verified** chip, and lists the record to publish: @@ -93,42 +93,46 @@ Domain verification requires publishing a record under the from address's domain ## Testing the Connection -In the **Delivery health** panel, click **Send test message**. The **Send the test to** field beside it accepts an address, and is optional. +In the **Delivery health** panel, click **Test connection**. -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." +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 proves that the server accepts the connection and the credentials, and nothing more. **It sends no message.** There is no recipient to choose, because none is used. On success the tab reports "The mail server accepted the connection. 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). {{< /alert >}} -A passing test is a prerequisite for turning the server on. A failing test names the stage that refused the connection; use [Troubleshooting](#troubleshooting) to act on it. +A passing test is a prerequisite for turning the server on, and it stamps **Last success** in the **Delivery health** panel. A failing test names the stage that refused the connection; use [Troubleshooting](#troubleshooting) to act on it. ## Turning the Server On -With the domain verified and a test passed, click **Turn on** in the **Delivery health** panel. The tab confirms with "Mail server turned on. It will carry mail once a delivery succeeds." +With the domain verified and a test passed, click **Turn on** in the **Delivery health** panel. The tab confirms with "Mail server turned on. Mail for *your Organization* now goes out through it." -Layer5 Cloud refuses to turn a server on before it has passed a test, with the message "the mail relay must pass a test before it can be enabled; run the test operation first". The button is also disabled while the domain is unverified, and the panel says "Verify the from domain before turning this server back on." +Both preconditions are enforced on the button, and the panel says which one is outstanding: "Pass a connection test before turning this server on." and "Verify the from domain before turning this server on." The API enforces the test independently, refusing to enable a server whose last verdict is not a success with the message "the mail relay must pass a test before it can be enabled; run the test operation first". From this point, application mail for your Organization's members leaves through your server from your from address. The from display name is the one you configured, and the Reply-To header carries your Reply-To address if you set one. ### Reading the status -The status chip beside the heading reports one of four states: +The status chip beside the heading reports one of four states. It is derived from two facts - whether the server is turned on, and how the last connection test or delivery through it went - so a decision somebody made is never reported as a fault: | Chip | Meaning | | --- | --- | -| **Not yet proven** | Configured, but no message has been delivered through it yet. Mail is still going out through the shared mail server. | -| **Delivering** | The last delivery attempt through your server succeeded, and mail for this Organization is leaving through it. | -| **Failing** | The last delivery attempt through your server failed. The **Last failure** line names the reason, and what happened to the message depends on your fallback setting. Layer5 Cloud keeps trying your server on the next message. | -| **Turned off** | An administrator turned the server off. Mail is going out through the shared mail server. | +| **Off** | The server is not turned on: either nobody has turned it on yet, or an administrator turned it off. Mail is going out through the shared mail server. This is also what a newly saved configuration reads as, and what any settings save or password rotation returns it to. | +| **Delivering** | The server is on and the last connection test or delivery through it succeeded. Mail for this Organization is leaving through it. | +| **Failing** | The server is on and the last connection test or delivery through it failed. The **Last failure** line names the reason, and what happened to that message depends on your fallback setting. Your server is still used for the next message. | +| **Not yet proven** | The server is on and nothing has succeeded through it yet. Mail for this Organization is leaving through it. You are unlikely to see this: turning a server on requires a passed test, and every settings save turns it back off. | -The **Delivery health** panel also shows the **Server** host and port, the **From** address, when mail was **Last delivered**, and the count of **Consecutive failures** since the last success. When the last attempt failed, a **Last failure** line gives the time and the classified reason, using the same reasons as [Troubleshooting](#troubleshooting). +{{< alert title="Failing does not take your server out of service" type="info" >}} +There is no circuit that stops using a server after repeated failures. **Failing** describes the last attempt and nothing more; the next message is sent through your server just the same. If it keeps failing, fix the cause named on the **Last failure** line - the status will not recover on its own, and it will not deteriorate into your server being skipped either. +{{< /alert >}} + +The **Delivery health** panel also shows the **Server** host and port, the **From** address, the time of the **Last success**, and the count of **Consecutive failures**. That count means delivery failures since the last success: a failed connection test does not advance it, and neither does a rejection of one recipient's address, which says nothing about the server. When the last attempt failed, a **Last failure** line gives the time and the classified reason, using the same reasons as [Troubleshooting](#troubleshooting). ## Fallback **Fall back to the shared mail server when delivery fails** is on by default. It decides what happens to a message your server does not accept. -**With fallback on**, a message your server refuses is re-sent through Layer5's shared mail server, and the failure is recorded against your server's delivery health. The re-sent message cannot claim your from address, because Layer5's server is not authorized to send as your domain and the message would fail your own SPF and DMARC checks. Instead it arrives from Layer5's address with a display name of your Organization's name followed by "(via Layer5)", and its Reply-To is your Reply-To address, or your from address if you did not set one. Your members still receive the message. Your Organization's name still appears on it. +**With fallback on**, a message your server does not accept is re-sent through Layer5's shared mail server, and the failure is recorded against your server's delivery health. "Does not accept" is every way a delivery can fail against your server, not only a refusal it voiced: a host nobody can reach, a connection that times out, a TLS handshake that fails and a rejected password all take the same path. The re-sent message cannot claim your from address, because Layer5's server is not authorized to send as your domain and the message would fail your own SPF and DMARC checks. Instead it arrives from Layer5's address with a display name of your Organization's name followed by "(via Layer5)", and its Reply-To is your Reply-To address, or your from address if you did not set one. Your members still receive the message. Your Organization's name still appears on it. **With fallback off**, your Organization owns delivery entirely. A message your server does not accept is dropped and is not re-sent. Turning it off is a deliberate decision, so the tab asks you to confirm it with the dialog **Turn off fallback to the shared mail server?**, which states the consequence in full: @@ -136,13 +140,16 @@ The **Delivery health** panel also shows the **Server** host and port, the **Fro Leave fallback on unless you have a specific reason to accept dropped mail. If you do turn it off, watch the **Delivery health** panel: with fallback off, **Failing** means members did not receive that message. -One exception applies whatever the setting: if Layer5 Cloud cannot read your stored password, that is a fault on Layer5's side and not a delivery policy you chose, so the message is sent through the shared server regardless and the failure is recorded as "The stored password could not be read." +Two exceptions apply whatever the setting: + +- **A password Layer5 Cloud cannot read.** That is a fault on Layer5's side and not a delivery policy you chose, so the message is sent through the shared server regardless and the failure is recorded as "The stored password could not be read." +- **A server that took the whole message and then went away.** If your server accepts the message body and then drops the connection or stops answering instead of confirming it, the outcome is genuinely unknown - it may have queued the message. Re-sending could deliver it twice, so nothing more is sent, whichever way fallback is set. The failure is still recorded against your server's delivery health. ## Managing the Configuration Afterwards ### Changing settings -The **Mail server settings** panel holds the same fields as the setup form, minus the password, with its own **Provider preset** picker and **Save settings** button. Saving confirms with "Mail server settings saved. The stored password is unchanged." Any settings save returns the server to unproven and turns it off, because a host or port nothing has tested is unproven. Run the connection test and click **Turn on** again afterwards. Changing the from address to a different domain also resets domain verification. +The **Mail server settings** panel holds the same fields as the setup form, minus the password, with its own **Provider preset** picker and **Save settings** button. Saving confirms with "Mail server settings saved. The stored password is unchanged." Any settings save returns the server to unproven and turns it off, because a host or port nothing has tested is unproven; the recorded test result, failure reason and failure count are cleared with it. Run the connection test and click **Turn on** again afterwards. Your from-domain proof survives an edit that leaves the from address on the same domain - renaming the display name does not cost you the TXT record - but changing the from address to a different domain resets domain verification. ### Replacing the password @@ -154,11 +161,11 @@ Paste the password exactly. Leading and trailing whitespace is kept, because it ### Turning it off -Click **Turn off** in the **Delivery health** panel. The dialog **Turn off this mail server?** explains that mail goes back to Layer5's shared server and stops arriving from your domain, and that the configuration and stored password are kept so you can turn it back on. Turning it back on requires the domain to still be verified. +Click **Turn off** in the **Delivery health** panel. The dialog **Turn off this mail server?** explains that mail goes back to Layer5's shared server and stops arriving from your domain, and that the configuration and stored password are kept so you can turn it back on. The tab confirms with "Mail server turned off. Mail is going out through Layer5 again." The chip returns to **Off**, and the recorded test result is kept, so turning it back on needs only the domain to still be verified. ### Removing it -The **Stop using your own mail server** panel's **Remove mail server** button deletes the configuration and the stored password together. The dialog **Remove this mail server?** states that this cannot be undone. Mail is not interrupted: every message leaves through Layer5's shared server from the moment the configuration is removed. Re-adding means entering the host, credentials and from address again, and verifying the domain again. +The **Stop using your own mail server** panel's **Remove mail server** button deletes the configuration and the stored password together. The dialog **Remove this mail server?** states that this cannot be undone, and the tab confirms with "Removed *your Organization*'s mail server. Mail is going out through Layer5 again." Mail is not interrupted: every message leaves through Layer5's shared server from the moment the configuration is removed. Re-adding means entering the host, credentials and from address again, and verifying the domain again. ## Google Workspace @@ -168,6 +175,14 @@ Google supports two ways for an application to send through your Workspace domai Google Workspace [no longer supports less secure apps](https://knowledge.workspace.google.com/admin/apps/control-access-to-less-secure-apps) that sign in with a username and password, and the setting to allow them has been removed from the Admin console. An application sending over SMTP must present an [app password](https://support.google.com/accounts/answer/185833), which requires 2-Step Verification to be turned on for that account. A sign-in password pasted into the **Password** field produces "The server rejected the username and password." on test. That is Google refusing the credential, not a fault in Layer5 Cloud. {{< /alert >}} +### App passwords, and Google's "you must use OAuth" + +Google's own pages say that third-party apps must use OAuth, and a reader who finds that paragraph will reasonably ask why this guide asks for an app password. Both are true, and the exception is the point. + +What Google turned off on 14 March 2025 is sign-in with the **account** password. Its [transition article](https://knowledge.workspace.google.com/admin/sync/transition-from-less-secure-apps-to-oauth) states that from that date "You will no longer use a password for access (with the exception of app passwords)", and for this exact case - "scanners or other devices using SMTP" - it lists "Configure an app password for use with the device" beside configuring OAuth. [App passwords](https://support.google.com/accounts/answer/185833) remain available, and "can only be used with accounts that have 2-Step Verification turned on". + +So an app password is the credential to use here. **Layer5 Cloud does not support OAuth (`XOAUTH2`) for outbound mail**: it authenticates with `PLAIN` or `CRAM-MD5`, which is why it needs a password rather than a token. Google is explicit that it prefers neither - it says app passwords "aren't recommended and are unnecessary in most cases" - and its recommended path for an application is the relay service authenticating by source IP address instead of by credential. Hosted Layer5 Cloud cannot take that path, because it publishes no fixed sending addresses for you to allow. A self-hosted Layer5 Cloud that egresses from a static address can: allow that address on the relay and set **Authentication** to `none`. + ### Path A: the SMTP relay service This is [Google's recommended path for applications and devices](https://knowledge.workspace.google.com/admin/gmail/advanced/route-outgoing-smtp-relay-messages-through-google) and it lets you send from any address in your domain, such as `no-reply@`. @@ -175,7 +190,7 @@ This is [Google's recommended path for applications and devices](https://knowled In the Google Admin console, go to **Menu > Apps > Google Workspace > Gmail > Routing**, scroll to **SMTP relay service** and click **Configure**. Set: - **Allowed senders**: **Only addresses in my domains**. Google states that with this option the sender does not have to be a Workspace user, but the address must be in your primary domain or a subdomain of it. -- **Authentication**: **Require SMTP Authentication**. Google describes this as verifying the connection with a Workspace user's email address and password. Do not rely on the IP-address option: Layer5 Cloud publishes no fixed sending addresses to allow. +- **Authentication**: **Require SMTP Authentication**. Google describes this as verifying the connection with a Workspace user's email address and password. Do not rely on the IP-address option on hosted Layer5 Cloud, which publishes no fixed sending addresses to allow; see [App passwords, and Google's "you must use OAuth"](#app-passwords-and-googles-you-must-use-oauth) for the self-hosted exception. - **Encryption**: **Require TLS encryption**. Then on the Email tab: @@ -214,6 +229,115 @@ The constraint is the from address. In practice, Gmail's SMTP server replaces th - **Verification.** Your Workspace domain is a domain you control, so the TXT record in [Proving You Control the Sending Domain](#proving-you-control-the-sending-domain) is published like any other record at your DNS host. A personal `@gmail.com` address cannot complete this step. - **Mail authentication.** Your Workspace domain already carries Google's SPF include, and DKIM signing applies once it is turned on in the Admin console under **Menu > Apps > Google Workspace > Gmail > Authenticate email**. Google notes it can take up to 48 hours for DKIM authentication to start working after the key is added. Confirm DKIM is on for the domain: [Set up DKIM](https://knowledge.workspace.google.com/admin/security/set-up-dkim). No other mail-authentication DNS is needed beyond Layer5 Cloud's TXT proof record. +## Microsoft 365 + +The **Microsoft 365** preset fills Microsoft's [client SMTP submission](https://learn.microsoft.com/en-us/exchange/mail-flow-best-practices/how-to-set-up-a-multifunction-device-or-application-to-send-email-using-microsoft-365-or-office-365) endpoint, which sends authenticated mail through a cloud mailbox. + +| Field | Value | +| --- | --- | +| SMTP Host | `smtp.office365.com` | +| Port | `587` | +| Encryption | `starttls` | +| Authentication | `plain` | +| Username | the sign-in address of a licensed mailbox in your tenant | +| Password | that mailbox's password | +| From Address | that same mailbox's address, unless you grant **Send As** (below) | + +Microsoft names port 587 or 25 for this path and requires TLS 1.2 or later. It also states that a device defaulting to port 465 "doesn't support the required versions of TLS for client SMTP submission", so choose `starttls` on 587 and not `tls` on 465. + +Four things decide whether this works, and each of them produces a specific failure: + +- **SMTP AUTH is off by default.** Microsoft disables authenticated client SMTP submission for organizations created after January 2020, and it is turned on per mailbox. Enable it for the mailbox you are using - see [Enable or disable authenticated client SMTP submission](https://learn.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/authenticated-client-smtp-submission) - or the test returns "SMTP authentication was refused by the mail server". +- **The authentication mechanism has to be one Layer5 Cloud offers.** Layer5 Cloud implements `PLAIN` and `CRAM-MD5` and does not implement `AUTH LOGIN`; the preset says so beneath the picker. A tenant that will not accept `AUTH PLAIN` returns "The mail server does not support the selected authentication method", and no setting on this page changes that. Use a mailbox whose tenant accepts `AUTH PLAIN`, or one of the alternatives below. +- **Security defaults block this path entirely.** Microsoft states that client SMTP submission using basic authentication "isn't compatible with Security defaults in Microsoft Entra ID". A tenant with [security defaults](https://learn.microsoft.com/en-us/entra/fundamentals/security-defaults) on cannot use this path at all. +- **Sending as a different address needs Send As.** If the from address is not the mailbox you authenticate with, that mailbox needs **Send As** permission on it; Microsoft returns "5.7.60 SMTP; Client doesn't have permissions to send as this sender", which arrives here as the **Last failure** "The server refused the from address." A connection test cannot detect it, because the test never names a sender. + +Microsoft's stated limits for this path are 10,000 recipients per day and 30 messages per minute. + +{{< alert title="Basic authentication for client submission is being retired" type="warning" >}} +Microsoft has [published a deprecation timeline](https://techcommunity.microsoft.com/blog/exchange/updated-exchange-online-smtp-auth-basic-authentication-deprecation-timeline/4489835) for basic authentication on client SMTP submission: behaviour is unchanged through December 2026, after which it is disabled by default for existing tenants and unavailable to new ones, with a final removal date to be announced in the second half of 2027. Because Layer5 Cloud authenticates with a username and password, a tenant that reaches that cut-off without the setting re-enabled will start failing with "The server rejected the username and password." Plan a move to a provider on this page that authenticates with a token, or keep the setting enabled while Microsoft still allows it. +{{< /alert >}} + +Microsoft's two alternatives to client submission do not substitute cleanly here, and it is worth knowing why before you try them: + +- **High Volume Email** (`smtp.hve.mx.microsoft`, port 587) accepts basic authentication on a dedicated endpoint even where SMTP AUTH is disabled, but Microsoft states it delivers to [internal recipients within the tenant only](https://learn.microsoft.com/en-us/exchange/mail-flow-best-practices/high-volume-mails-m365). It can only carry your Organization's mail if every member has a mailbox in your tenant, and it needs pay-as-you-go billing configured before the account can send at all. +- **SMTP relay** through your tenant's MX endpoint authenticates by certificate or static IP on port 25 rather than by credential. Hosted Layer5 Cloud publishes no fixed sending addresses to allow, so this is only an option for a self-hosted install with a static egress address, configured with **Authentication** set to `none`. + +## Amazon SES + +The **Amazon SES** preset fills a regional endpoint, and **the region in it is a placeholder you must replace**. The preset ships `email-smtp.us-east-1.amazonaws.com`; if you send from another region, the host is wrong and nothing will work until you change it. + +| Field | Value | +| --- | --- | +| SMTP Host | `email-smtp..amazonaws.com`, for example `email-smtp.eu-west-1.amazonaws.com`. AWS lists every endpoint under [Amazon SES endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/ses.html). | +| Port | `587` for STARTTLS, or `465` for implicit TLS | +| Encryption | `starttls` on 587, `tls` on 465 | +| Authentication | `plain` | +| Username | your SES SMTP user name | +| Password | your SES SMTP password | +| From Address | an address on an identity you have verified in SES, in the same region | + +- **SES SMTP credentials are not your AWS access keys.** AWS states plainly that "Your SMTP password is different from your AWS secret access key". Create a dedicated pair in the SES console under **SMTP settings** > **Create SMTP credentials**, and download them at that point - they cannot be retrieved afterwards. See [Obtaining Amazon SES SMTP credentials](https://docs.aws.amazon.com/ses/latest/dg/smtp-credentials.html). Credentials are **unique to each region**, so a set minted for one region will not authenticate against another region's endpoint. +- **Sandbox accounts cannot mail your members.** A new SES account is in the [sandbox](https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html) in every region, where you can send only to verified addresses and domains, at most 200 messages per 24 hours and 1 per second. Your Organization's members are not verified identities, so their mail is refused - recorded here as "The server refused the recipient." Request production access before turning the server on. +- **Two separate verifications apply.** SES requires you to verify the identity you send as, and Layer5 Cloud requires its own TXT proof of the same domain. Neither substitutes for the other; do both. +- **Use 587 or 465, not SES's alternates.** AWS also documents ports 2587 and 2465. Layer5 Cloud permits only `25`, `465`, `587` and `2525`, so either alternate is refused before any connection is made. + +## SendGrid + +The **SendGrid** preset fills its SMTP relay, where the credential is an API key rather than an account login. + +| Field | Value | +| --- | --- | +| SMTP Host | `smtp.sendgrid.net` | +| Port | `587` | +| Encryption | `starttls` | +| Authentication | `plain` | +| Username | `apikey` | +| Password | your SendGrid API key | +| From Address | an address on an authenticated domain, or a verified single sender | + +{{< alert title="The username is the word apikey" type="warning" >}} +The **Username** field takes the literal string `apikey` - seven characters, the same for every account. It is not your email address, not your SendGrid login and not the API key itself. The API key goes in the **Password** field. Entering the key in both fields, or your email address as the username, produces "The server rejected the username and password." The preset shows this caveat beneath the picker for the same reason. +{{< /alert >}} + +- **Create the key with Mail Send permission**, and copy it when it is shown: SendGrid displays an API key once and cannot show it again. See [Integrating with the SMTP API](https://www.twilio.com/docs/sendgrid/for-developers/sending-email/integrating-with-the-smtp-api). +- **Verify the sender identity first.** SendGrid requires every sending address to be covered by [domain authentication or single sender verification](https://www.twilio.com/docs/sendgrid/for-developers/sending-email/sender-identity), and describes single sender verification as suitable for testing only. Authenticate the domain your from address is on. Unverified, delivery is refused and recorded as "The server refused the from address." +- **Other ports.** SendGrid documents 25, 587 and 2525 for STARTTLS and 465 for implicit TLS. All four are within Layer5 Cloud's allowlist; 587 with `starttls` is the recommended pairing. + +## Postmark + +The **Postmark** preset fills its transactional SMTP endpoint. Its credential is unusual: the same token goes in both fields. + +| Field | Value | +| --- | --- | +| SMTP Host | `smtp.postmarkapp.com` | +| Port | `587` | +| Encryption | `starttls` | +| Authentication | `plain` | +| Username | your Postmark **Server API token** | +| Password | the same Server API token | +| From Address | an address on a verified domain, or a confirmed Sender Signature | + +- **Username and password are both the Server API token.** Postmark documents that "The Server API Token acts as the username and password". It is per-server, so take it from the server you intend the mail to come from. An SMTP token works too, with its access key as the username and its secret key as the password. See [Send email with SMTP](https://postmarkapp.com/developer/user-guide/send-email-with-smtp). +- **The from address must be verified with Postmark.** Postmark requires a confirmed Sender Signature for a single address, or a [verified domain](https://postmarkapp.com/support/article/1046-how-do-i-verify-a-domain) to send from any address on it. Verifying the domain is the better fit, since your from address and Reply-To are usually on the same domain. Without it, delivery is refused and recorded as "The server refused the from address." +- **Mail goes to the default transactional stream.** Postmark selects a message stream from a header that Layer5 Cloud does not send, so messages take the server's default `outbound` transactional stream. That is the right stream for the notification, invitation and account mail this feature carries. Postmark's separate broadcast host is not applicable here. +- **There is no implicit-TLS port.** Postmark documents 25, 2525 and 587, all with STARTTLS. Do not choose the `tls` encryption mode; pair `starttls` with 587. + +## Any Other Provider + +Choose the **Custom** preset - it fills nothing and leaves whatever you typed alone - and get these four things from your provider's documentation. They map one-to-one onto [Requirements on the mail server](#requirements-on-the-mail-server): + +| What to ask your provider | What to do with it | +| --- | --- | +| The submission hostname and port | Enter them as **SMTP Host** and **Port**. The port has to be `25`, `465`, `587` or `2525`; if your provider names only something else, it cannot be used. | +| Whether that port expects STARTTLS or implicit TLS | Set **Encryption** to match: `starttls` for 587-style ports, `tls` for 465. A mismatch fails as "The TLS handshake failed." | +| How the SMTP credential is minted | Almost never your account password. Enter it as **Username** and **Password** with **Authentication** set to `plain`, or `cram-md5` if the provider offers it and you prefer that the password never crosses the wire. | +| Which from addresses the account may send as | Providers vary from "any address on a verified domain" to "the authenticated mailbox only". Confirm your from address is authorized, because the connection test cannot check it. | + +Two constraints rule some providers out before you start. The server must resolve to a public address, so an internal relay is unreachable from hosted Layer5 Cloud. And a server that offers only `AUTH LOGIN` cannot be used, because Layer5 Cloud implements `PLAIN` and `CRAM-MD5` and will not fall back to `LOGIN`. + +**Authentication** set to `none` is for one case only: a relay that authorizes by source address rather than by credential. That needs a fixed egress address to allow, which hosted Layer5 Cloud does not publish, so in practice it is a self-hosted option. + ## Troubleshooting A refused test shows a one-line result beneath the **Send test message** button, and the **Last failure** line in **Delivery health** shows the classified reason recorded for the most recent failure, whether that was a test or a real delivery. Neither is the mail server's own reply. Both name the stage that failed, which is what tells you where to look. @@ -221,22 +345,22 @@ A refused test shows a one-line result beneath the **Send test message** button, | The test result says | The Last failure line says | What it means | What to do | | --- | --- | --- | --- | | "The mail server address is one this server will not connect to" | "The address the host resolved to is not a permitted destination." | The host resolved to a loopback, private, link-local or carrier-shared address. Layer5 Cloud will not connect to those. | Use a mail server with a public address. An internal relay cannot be used from hosted Layer5 Cloud. | -| "The mail transport is not usable: port is invalid" | "The server refused the message." | The port is not one of `25`, `465`, `587` or `2525`. The form accepts any port; the allowlist is applied when you test, before any connection is made, so the recorded reason is the generic one. | Change the port to the submission port your provider names. | +| "The mail server address is one this server will not connect to" | "The address the host resolved to is not a permitted destination." | The port is not one of `25`, `465`, `587` or `2525`. The form accepts any port in range; the allowlist is applied when you test, before any connection is made, and it reports the same way an unreachable address does. | Change the port to the submission port your provider names. Several providers document alternates - SES's `2587` and `2465`, for instance - that are outside this list. | | "The selected authentication method sends the password in the clear, so it cannot be used on an unencrypted connection. ..." | "The server refused the message." | You paired a password with `none` encryption. The check runs before any connection is made. | Choose `starttls` or `tls`. | | "Unable to open a mail session with the configured server" | "The server refused the connection." | Something answered at that address but nothing is listening on that port. | Check the port. Check that the host is the SMTP submission endpoint, not a web address. | | "Unable to open a mail session with the configured server" | "The server did not answer in time." | The connection attempt timed out, or the server opened the connection and then went silent, including part-way through authentication. | Check the host and port. A firewall on the server side silently dropping the connection produces this result. | | "Unable to open a mail session with the configured server" | "The TLS handshake failed." | Encryption negotiation failed. The most common cause is a mismatched pairing: `tls` on port 587 or `starttls` on port 465. A certificate that is not trusted or does not name the host also lands here. | Match the mode to the port: `starttls` on 587, `tls` on 465. Check the server's certificate. | | "The mail server does not offer STARTTLS" | "The server does not offer STARTTLS." | You chose `starttls` and the server did not advertise it. Layer5 Cloud refuses to continue unencrypted rather than send your password in the clear. | If the port is 465, choose `tls`. Otherwise enable STARTTLS on the server. | -| "SMTP authentication was refused by the mail server" | "The server rejected the username and password." | The server answered the credential with a refusal. | Re-enter the password with **Replace password**. For Google Workspace, use an app password, never the sign-in password. For SendGrid, the username is `apikey`. | +| "SMTP authentication was refused by the mail server" | "The server rejected the username and password." | The server answered the credential with a refusal. | Re-enter the password with **Replace password**. For Google Workspace, use an app password, never the sign-in password. For SendGrid, the username is `apikey`. For Microsoft 365, check that SMTP AUTH is enabled on the mailbox. For Amazon SES, check you used SES SMTP credentials rather than AWS access keys. | | "The mail server does not support the selected authentication method" | "The server rejected the username and password." | The server answered that it does not implement the mechanism you chose, or does not offer it on this connection. | Choose a mechanism the server advertises. `AUTH LOGIN` is not supported by Layer5 Cloud, so a server that offers nothing else cannot be used. | | "The mail server requires an encrypted connection for the selected authentication method" | "The server rejected the username and password." | The server accepts authentication only over an encrypted connection. | Choose `starttls` or `tls`. | | "The mail server temporarily declined authentication, and no setting needs to change" | "The server rejected the username and password." | The server is greylisting or rate-limiting the connection. | Retry in a few minutes before changing anything. | | "The mail server answered reply code ... to the authentication attempt" | "The server rejected the username and password." | The server refused at the authentication stage with a reply Layer5 Cloud does not classify. | Check the mail server's logs for the reply. | -| Not shown by a test | "The server refused the from address." | A real delivery reached the server and it would not send as your from address. The test cannot detect this. | Authorize the from address on the server. For Google, register it as a verified **Send mail as** alias or use the SMTP relay service. | +| Not shown by a test | "The server refused the from address." | A real delivery reached the server and it would not send as your from address. The test cannot detect this. | Authorize the from address on the server: a verified **Send mail as** alias or the SMTP relay service for Google, **Send As** permission for Microsoft 365, a verified identity for Amazon SES, an authenticated domain for SendGrid, a verified domain or Sender Signature for Postmark. | | Not shown by a test | "The server refused the recipient." | A real delivery reached the server and it would not relay to that recipient. | Check the server's relay restrictions. The relay must accept external recipients. | | Not shown by a test | "The server refused the message." | A real delivery reached the server, which accepted sender and recipient and then refused the message itself, typically on a size or content policy. | Check the server's message policies and logs. | | Not shown by a test | "The stored password could not be read." | Layer5 Cloud could not decrypt the stored password. This is not a configuration mistake on your side, and the message was sent through the shared server regardless of your fallback setting. | Contact Layer5 support. Replacing the password with **Replace password** re-encrypts it and may clear the condition. | -| "Test message delivered." but mail arrives from the wrong address | Nothing recorded | The server accepted your credentials but sends as the authenticated account instead of your from address. Typical of `smtp.gmail.com`. | See [Google Workspace, Path B](#path-b-the-gmail-smtp-server). | +| A passing test, but mail arrives from the wrong address | Nothing recorded | The server accepted your credentials but sends as the authenticated account instead of your from address. Typical of `smtp.gmail.com`. | See [Google Workspace, Path B](#path-b-the-gmail-smtp-server). | | **Failing** with fallback off | Any of the above | Members did not receive the message that failed. | Fix the cause named on the **Last failure** line. Consider turning fallback on until it is fixed. | {{< alert title="Why the reasons are classifications" type="info" >}} From fc2be882fb02f031b46e818dcd0910d15b6efb9c Mon Sep 17 00:00:00 2001 From: James <160366376+hortison@users.noreply.github.com> Date: Tue, 8 Sep 2026 11:22:56 -0500 Subject: [PATCH 2/3] docs(cloud): resolve the credential contradiction and use American English Review findings on #1236. The "What You Will Need" list asserted that a hosted provider's credential is never the password you sign in with, and the Microsoft 365 example then had the reader enter exactly that. Replaces the rule with a table that states the username and password each provider expects, and names Microsoft 365 as the exception it is: client submission authenticates with the mailbox's own sign-in credential, where the tenant still permits it. The Microsoft 365 section says the same where the reader meets it. American English per .github/copilot-instructions.md: behaviour -> behavior, white-labelled -> white-labeled. Swept the whole file rather than the two lines that were reported. One British spelling is kept deliberately. "Authentication (None only for a relay that authorises by IP)" is the field label verbatim from ui/components/identity/org-management/org-smtp-form-schema.ts, and a reader matches it against the screen; correcting it here would put the guide out of step with the product. The spelling belongs upstream in meshery-cloud if anywhere. Signed-off-by: James <160366376+hortison@users.noreply.github.com> --- .../bring-your-own-mail-server.md | 23 +++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/content/en/cloud/guides/organizations/org-management/bring-your-own-mail-server.md b/content/en/cloud/guides/organizations/org-management/bring-your-own-mail-server.md index 07328b7cc61..8738e402345 100644 --- a/content/en/cloud/guides/organizations/org-management/bring-your-own-mail-server.md +++ b/content/en/cloud/guides/organizations/org-management/bring-your-own-mail-server.md @@ -22,9 +22,22 @@ Organization Administrators and Owners can configure, test, turn on, turn off, a Have these in hand before you open the Email tab: - **The hostname and submission port of your SMTP server**, and whether it uses STARTTLS or implicit TLS. -- **A username and password the server accepts.** For hosted providers this is an app password or a dedicated SMTP credential, not the password you sign in with. Each provider mints it somewhere different: see [Google Workspace](#google-workspace), [Microsoft 365](#microsoft-365), [Amazon SES](#amazon-ses), [SendGrid](#sendgrid) and [Postmark](#postmark) below. +- **A username and password the server accepts.** Which credential that is differs by provider, and for most of them it is not the password you sign in with. The table below says which one each provider expects. - **A from address on a domain whose DNS you control.** You prove control by publishing a TXT record, so you need access to the domain's DNS zone. +### Where each provider's credential comes from + +Every provider on this page mints its SMTP credential somewhere different, and getting the wrong one produces the same result in every case: "The server rejected the username and password." Follow the link for how to create it and what else that provider requires. + +| Provider | Username | Password | +| --- | --- | --- | +| [Google Workspace](#google-workspace) | the sending account's full address | an app password for that account, never its account password | +| [Microsoft 365](#microsoft-365) | the mailbox's sign-in address | that mailbox's own sign-in password. This is the exception on this page: client submission authenticates with the account credential itself, and only where the tenant permits it | +| [Amazon SES](#amazon-ses) | your SES SMTP user name | your SES SMTP password, which is not an AWS access key | +| [SendGrid](#sendgrid) | the literal string `apikey` | your SendGrid API key | +| [Postmark](#postmark) | your Postmark server API token | the same server API token again | +| [Any other provider](#any-other-provider) | whatever that provider documents for SMTP submission | | + ### Requirements on the mail server Layer5 Cloud refuses a configuration that does not meet these, so check them first: @@ -222,7 +235,7 @@ This path needs [no Admin console change](https://knowledge.workspace.google.com Google states the sending limit for this server is 2,000 messages per day. -The constraint is the from address. In practice, Gmail's SMTP server replaces the From address with the signed-in account's address unless that address is one of the account's configured **Send mail as** addresses. Google's help pages do not state this rewrite; it is what happens. Your members then see mail arrive from the account rather than from the address you configured, and the connection test cannot catch it, because it hangs up before naming a sender. If you want to send as `no-reply@example.com` through this path, [add it as a Send mail as address](https://support.google.com/mail/answer/22370) on the authenticating account and complete Google's confirmation step first. For a white-labelled sender, Path A is the better choice precisely because the relay service has no such constraint: with **Only addresses in my domains** it sends as any address in your domain. +The constraint is the from address. In practice, Gmail's SMTP server replaces the From address with the signed-in account's address unless that address is one of the account's configured **Send mail as** addresses. Google's help pages do not state this rewrite; it is what happens. Your members then see mail arrive from the account rather than from the address you configured, and the connection test cannot catch it, because it hangs up before naming a sender. If you want to send as `no-reply@example.com` through this path, [add it as a Send mail as address](https://support.google.com/mail/answer/22370) on the authenticating account and complete Google's confirmation step first. For a white-labeled sender, Path A is the better choice precisely because the relay service has no such constraint: with **Only addresses in my domains** it sends as any address in your domain. ### Both paths @@ -240,9 +253,11 @@ The **Microsoft 365** preset fills Microsoft's [client SMTP submission](https:// | Encryption | `starttls` | | Authentication | `plain` | | Username | the sign-in address of a licensed mailbox in your tenant | -| Password | that mailbox's password | +| Password | that mailbox's own sign-in password, where the tenant permits it | | From Address | that same mailbox's address, unless you grant **Send As** (below) | +Microsoft 365 is the one provider on this page whose SMTP credential **is** the account's sign-in password rather than a separate token or app password, so the caveats below are about whether your tenant still allows that, not about where to mint something else. + Microsoft names port 587 or 25 for this path and requires TLS 1.2 or later. It also states that a device defaulting to port 465 "doesn't support the required versions of TLS for client SMTP submission", so choose `starttls` on 587 and not `tls` on 465. Four things decide whether this works, and each of them produces a specific failure: @@ -255,7 +270,7 @@ Four things decide whether this works, and each of them produces a specific fail Microsoft's stated limits for this path are 10,000 recipients per day and 30 messages per minute. {{< alert title="Basic authentication for client submission is being retired" type="warning" >}} -Microsoft has [published a deprecation timeline](https://techcommunity.microsoft.com/blog/exchange/updated-exchange-online-smtp-auth-basic-authentication-deprecation-timeline/4489835) for basic authentication on client SMTP submission: behaviour is unchanged through December 2026, after which it is disabled by default for existing tenants and unavailable to new ones, with a final removal date to be announced in the second half of 2027. Because Layer5 Cloud authenticates with a username and password, a tenant that reaches that cut-off without the setting re-enabled will start failing with "The server rejected the username and password." Plan a move to a provider on this page that authenticates with a token, or keep the setting enabled while Microsoft still allows it. +Microsoft has [published a deprecation timeline](https://techcommunity.microsoft.com/blog/exchange/updated-exchange-online-smtp-auth-basic-authentication-deprecation-timeline/4489835) for basic authentication on client SMTP submission: behavior is unchanged through December 2026, after which it is disabled by default for existing tenants and unavailable to new ones, with a final removal date to be announced in the second half of 2027. Because Layer5 Cloud authenticates with a username and password, a tenant that reaches that cut-off without the setting re-enabled will start failing with "The server rejected the username and password." Plan a move to a provider on this page that authenticates with a token, or keep the setting enabled while Microsoft still allows it. {{< /alert >}} Microsoft's two alternatives to client submission do not substitute cleanly here, and it is worth knowing why before you try them: From 21eb7673d9318ea99990006ec6cbe1b9a8bae8c5 Mon Sep 17 00:00:00 2001 From: James <160366376+hortison@users.noreply.github.com> Date: Tue, 8 Sep 2026 11:25:25 -0500 Subject: [PATCH 3/3] docs(cloud): fix the remaining review findings on the mail-server guide Four more from the same review round, all real on inspection. - The Troubleshooting intro still named the old "Send test message" button after the rest of the page moved to "Test connection". Mine to fix; missed it in the first pass. - Correcting the port row left it reading identically to the blocked-address row above it, so a reader could not tell which case they were in. Merged into one row that names both causes and both remediations. - The Microsoft 365 timeline said basic auth becomes "unavailable to new tenants". Microsoft's wording is that it is not available BY DEFAULT, and that administrators can still re-enable it on existing tenants. Restores both qualifiers. - The SES sandbox note said members' mail is refused outright. It is refused only where the recipient is not covered by a verified address or domain. Also switches AGENTS.md to American English, for the same repository guideline the guide follows. Signed-off-by: James <160366376+hortison@users.noreply.github.com> --- AGENTS.md | 6 +++--- .../cloud/guides/organizations/org-management/_index.md | 2 +- .../org-management/bring-your-own-mail-server.md | 9 ++++----- 3 files changed, 8 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e9fd1126b7e..4a8ab9816ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,14 +44,14 @@ A literal backslash inside inline HTML is a related trap: Goldmark reads the `\< (`content/en/kanvas/reference/keyboard-shortcuts.md` is the worked example) and confirm the built HTML, not the source, before committing. -## Documenting Layer5 Cloud behaviour +## Documenting Layer5 Cloud behavior The cloud guides describe a product that lives in `meshery-cloud`, so every product claim is verified against `origin/master` there, never against a summary. The screen strings are in -`ui/components/identity/org-management/`; the behaviour behind them is in `server/handlers/`. +`ui/components/identity/org-management/`; the behavior behind them is in `server/handlers/`. That repo's own `docs/reference/` and `docs/runbooks/` are the best starting point but are not -the arbiter - they have described behaviour the handlers do not implement. Confirm a capability +the arbiter - they have described behavior the handlers do not implement. Confirm a capability has a producer in the Go or TSX before writing it up: a contract enum member or a runbook sentence is not proof the feature ships. diff --git a/content/en/cloud/guides/organizations/org-management/_index.md b/content/en/cloud/guides/organizations/org-management/_index.md index 501feed7cb4..dd2bed9c276 100644 --- a/content/en/cloud/guides/organizations/org-management/_index.md +++ b/content/en/cloud/guides/organizations/org-management/_index.md @@ -77,7 +77,7 @@ Switching identity providers does not affect existing user accounts or login his The **Email** tab lets your Organization send application mail such as invitations and notifications through **its own SMTP server**, from **its own domain**, instead of through Layer5's shared mail server. Nothing about the message then points to a shared provider. -Setting it up has three steps, and mail keeps leaving through Layer5's shared server until all three are done: register the server and its credentials, prove control of the sending domain by publishing a DNS TXT record, and pass a connection test before turning the server on. The tab reports delivery health afterwards, and a fallback setting decides what happens to a message your server does not accept. +Setting it up has three steps: register the server and its credentials, prove control of the sending domain by publishing a DNS TXT record, and pass a connection test. Completing them changes nothing on its own - mail keeps leaving through Layer5's shared server until an administrator clicks **Turn on**, which is what switches routing over. The tab reports delivery health afterwards, and a fallback setting decides what happens to a message your server does not accept. The full walkthrough, including a worked example for Google Workspace, Microsoft 365, Amazon SES, SendGrid and Postmark, and a troubleshooting table for every failure the tab reports, is in [Bring Your Own Mail Server](bring-your-own-mail-server/). diff --git a/content/en/cloud/guides/organizations/org-management/bring-your-own-mail-server.md b/content/en/cloud/guides/organizations/org-management/bring-your-own-mail-server.md index 8738e402345..f53fc95e8d0 100644 --- a/content/en/cloud/guides/organizations/org-management/bring-your-own-mail-server.md +++ b/content/en/cloud/guides/organizations/org-management/bring-your-own-mail-server.md @@ -270,7 +270,7 @@ Four things decide whether this works, and each of them produces a specific fail Microsoft's stated limits for this path are 10,000 recipients per day and 30 messages per minute. {{< alert title="Basic authentication for client submission is being retired" type="warning" >}} -Microsoft has [published a deprecation timeline](https://techcommunity.microsoft.com/blog/exchange/updated-exchange-online-smtp-auth-basic-authentication-deprecation-timeline/4489835) for basic authentication on client SMTP submission: behavior is unchanged through December 2026, after which it is disabled by default for existing tenants and unavailable to new ones, with a final removal date to be announced in the second half of 2027. Because Layer5 Cloud authenticates with a username and password, a tenant that reaches that cut-off without the setting re-enabled will start failing with "The server rejected the username and password." Plan a move to a provider on this page that authenticates with a token, or keep the setting enabled while Microsoft still allows it. +Microsoft has [published a deprecation timeline](https://techcommunity.microsoft.com/blog/exchange/updated-exchange-online-smtp-auth-basic-authentication-deprecation-timeline/4489835) for basic authentication on client SMTP submission: behavior is unchanged through December 2026, after which it is disabled by default for existing tenants - administrators can still re-enable it - and not available by default to tenants created after that point, with a final removal date to be announced in the second half of 2027. Because Layer5 Cloud authenticates with a username and password, a tenant that reaches that cut-off without the setting re-enabled will start failing with "The server rejected the username and password." Plan a move to a provider on this page that authenticates with a token, or keep the setting enabled while Microsoft still allows it. {{< /alert >}} Microsoft's two alternatives to client submission do not substitute cleanly here, and it is worth knowing why before you try them: @@ -293,7 +293,7 @@ The **Amazon SES** preset fills a regional endpoint, and **the region in it is a | From Address | an address on an identity you have verified in SES, in the same region | - **SES SMTP credentials are not your AWS access keys.** AWS states plainly that "Your SMTP password is different from your AWS secret access key". Create a dedicated pair in the SES console under **SMTP settings** > **Create SMTP credentials**, and download them at that point - they cannot be retrieved afterwards. See [Obtaining Amazon SES SMTP credentials](https://docs.aws.amazon.com/ses/latest/dg/smtp-credentials.html). Credentials are **unique to each region**, so a set minted for one region will not authenticate against another region's endpoint. -- **Sandbox accounts cannot mail your members.** A new SES account is in the [sandbox](https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html) in every region, where you can send only to verified addresses and domains, at most 200 messages per 24 hours and 1 per second. Your Organization's members are not verified identities, so their mail is refused - recorded here as "The server refused the recipient." Request production access before turning the server on. +- **Sandbox accounts cannot mail your members.** A new SES account is in the [sandbox](https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html) in every region, where you can send only to verified addresses and domains, at most 200 messages per 24 hours and 1 per second. Any member whose address is not itself verified, and whose domain is not verified either, is refused - recorded here as "The server refused the recipient." Unless every member is covered by a verified identity, request production access before turning the server on. - **Two separate verifications apply.** SES requires you to verify the identity you send as, and Layer5 Cloud requires its own TXT proof of the same domain. Neither substitutes for the other; do both. - **Use 587 or 465, not SES's alternates.** AWS also documents ports 2587 and 2465. Layer5 Cloud permits only `25`, `465`, `587` and `2525`, so either alternate is refused before any connection is made. @@ -355,12 +355,11 @@ Two constraints rule some providers out before you start. The server must resolv ## Troubleshooting -A refused test shows a one-line result beneath the **Send test message** button, and the **Last failure** line in **Delivery health** shows the classified reason recorded for the most recent failure, whether that was a test or a real delivery. Neither is the mail server's own reply. Both name the stage that failed, which is what tells you where to look. +A failed test shows a one-line result beneath the **Test connection** button, and the **Last failure** line in **Delivery health** shows the classified reason recorded for the most recent failure, whether that was a test or a real delivery. Neither is the mail server's own reply. Both name the stage that failed, which is what tells you where to look. | The test result says | The Last failure line says | What it means | What to do | | --- | --- | --- | --- | -| "The mail server address is one this server will not connect to" | "The address the host resolved to is not a permitted destination." | The host resolved to a loopback, private, link-local or carrier-shared address. Layer5 Cloud will not connect to those. | Use a mail server with a public address. An internal relay cannot be used from hosted Layer5 Cloud. | -| "The mail server address is one this server will not connect to" | "The address the host resolved to is not a permitted destination." | The port is not one of `25`, `465`, `587` or `2525`. The form accepts any port in range; the allowlist is applied when you test, before any connection is made, and it reports the same way an unreachable address does. | Change the port to the submission port your provider names. Several providers document alternates - SES's `2587` and `2465`, for instance - that are outside this list. | +| "The mail server address is one this server will not connect to" | "The address the host resolved to is not a permitted destination." | Either the destination address or the port was refused before any connection was made, and both report the same way. **The address**: the host resolved to a loopback, private, link-local or carrier-shared address. **The port**: it is not one of `25`, `465`, `587` or `2525` - the form accepts any port in range, and the allowlist is applied when you test. | Check both. Use a mail server with a public address; an internal relay cannot be used from hosted Layer5 Cloud. Then check the port against your provider's submission port, remembering that several providers document alternates - SES's `2587` and `2465`, for instance - that are outside this list. | | "The selected authentication method sends the password in the clear, so it cannot be used on an unencrypted connection. ..." | "The server refused the message." | You paired a password with `none` encryption. The check runs before any connection is made. | Choose `starttls` or `tls`. | | "Unable to open a mail session with the configured server" | "The server refused the connection." | Something answered at that address but nothing is listening on that port. | Check the port. Check that the host is the SMTP submission endpoint, not a web address. | | "Unable to open a mail session with the configured server" | "The server did not answer in time." | The connection attempt timed out, or the server opened the connection and then went silent, including part-way through authentication. | Check the host and port. A firewall on the server side silently dropping the connection produces this result. |