diff --git a/content/en/cloud/guides/organizations/org-management/_index.md b/content/en/cloud/guides/organizations/org-management/_index.md index c6d9e84b75f2..021714f1d5cf 100644 --- a/content/en/cloud/guides/organizations/org-management/_index.md +++ b/content/en/cloud/guides/organizations/org-management/_index.md @@ -51,6 +51,7 @@ You can update your Organization's name, location, associated teams, branding, a - Logos: Upload specific logo versions for various display contexts by clicking the respective **"Upload"** buttons. - Invitations: Access a shareable link to invite users to your Organization. - Identity Providers: Configure which OAuth applications power your Organization's sign-in (see [Configuring Identity Providers](#configuring-identity-providers-bring-your-own-credentials) below). + - Email: Configure your Organization's own outbound mail server, so email reaches your members from your own domain (see [Configuring your own mail server](#configuring-your-own-mail-server) below). Editing Organization Details @@ -72,6 +73,64 @@ Organization Administrators and Owners can add, rotate, and remove their Organiz Switching identity providers does not affect existing user accounts or login history. Users who signed in through a provider you later remove may need to re-authenticate. +### Configuring your own mail server + +The **Email** tab lets your Organization send its email through **its own SMTP server**, from **its own address**, instead of through Layer5's shared mail server. + +By default, every notification, invitation, account-verification and password-recovery email for your Organization is delivered by Layer5 and arrives from a Layer5 address. The body of the message already carries your branding; only the envelope does not. Bringing your own mail server changes the envelope too, so your email aligns with your own SPF and DMARC policy. + +{{< alert title="This carries your sign-in email too" type="warning" >}} +Your mail server carries account verification and password recovery, not just notifications. A delivery problem therefore becomes a sign-in problem for your members. That is why **Fall back to the shared mail server** is switched on by default — leave it on unless you have a specific reason not to. +{{< /alert >}} + +#### What you will need + +- The hostname and submission port of your SMTP server, and whether it uses STARTTLS or implicit TLS. Ports 25, 465, 587 and 2525 are supported. +- A username and password your server accepts. For most hosted providers this is an **app password** or a dedicated SMTP credential, not your normal account password. +- A **from address** on a domain you can prove you control — either your Organization's registered custom domain, or a domain you can publish a DNS TXT record on. + +Your mail server must be reachable on the public internet. A relay on a private or internal network cannot be used. + +#### How to configure it + +1. Open **Edit Organization** and select the **Email** tab, then click **Configure mail server**. +2. Optionally pick a **Provider preset** — Gmail / Google Workspace, Microsoft 365, Amazon SES, SendGrid or Postmark. A preset fills only the host, port and encryption; the username and from address are always yours to enter. +3. Fill in the rest of the form and click **Save mail server**. Nothing about your email changes yet — mail keeps going out through Layer5 while you finish setting up. +4. **Verify your from domain.** If it matches your Organization's registered custom domain, it is verified immediately with no DNS record. Otherwise the page shows the exact TXT record to publish; publish it, then click **Re-check now**. DNS changes take time to propagate, so the first re-check often reports that no record was found. +5. **Send a test message.** You can address it to anyone; left empty it goes to you. Once a message is delivered successfully, your Organization's email starts going out through your own server. + +#### Reading the status + +The Email tab shows one of four states, and the difference between them matters: + +| Status | What it means | +| --- | --- | +| **Not yet proven** | Configured, but no message has been delivered through it yet. Email is still going out through Layer5. | +| **Delivering** | The last delivery succeeded. Your Organization's email is going out through your server. | +| **Failing** | Repeated failures stopped your server being contacted. What happens to a message now depends on your fallback setting. | +| **Turned off** | An administrator turned it off. Email is going out through Layer5. | + +If a test message is refused, the page explains what went wrong, the probable cause, and what to try — for example, an authentication rejection usually means your provider requires an app password rather than your account password. + +#### About your stored password + +Your password is encrypted before it is stored and is **never shown again**, on this page or through the API. + +Because of that, the settings form does not include a password field at all — saving your settings can never change or clear your stored password. Replacing it is a separate **Replace password** action, and its field is always empty when the page loads. + +#### Turning it off or removing it + +- **Turn off** returns your Organization to Layer5's shared mail server but keeps your configuration and stored password, so you can turn it back on later. +- **Remove mail server** deletes the configuration and the stored password. Your email is not interrupted — every message goes through Layer5's shared server from that moment — but re-adding means entering everything again and verifying your domain again. + +{{< alert title="Who can configure this" type="info" >}} +Organization Administrators and Owners can configure, test and remove their Organization's mail server themselves. +{{< /alert >}} + +{{< alert title="Microsoft 365 tenants requiring AUTH LOGIN" type="warning" >}} +Mail servers that require the `AUTH LOGIN` mechanism are not supported yet. If your Microsoft 365 tenant requires it, use an account that accepts `AUTH PLAIN`, or a Microsoft 365 high-volume SMTP relay. +{{< /alert >}} + ## Using the Open Organization Invitation Link To invite multiple users to your organization at once, or to allow open sign-ups (for example, for a public community), you can use the "Open Organization Invitation Link." This is a shareable link that lets users join directly. diff --git a/content/en/cloud/guides/self-hosted/operating/smtp.md b/content/en/cloud/guides/self-hosted/operating/smtp.md index 1f9035b72cd3..b4825a58ebb7 100644 --- a/content/en/cloud/guides/self-hosted/operating/smtp.md +++ b/content/en/cloud/guides/self-hosted/operating/smtp.md @@ -16,6 +16,20 @@ This guide explains how to diagnose email sending issues in Layer5 Cloud deploym Email issues in Layer5 Cloud can occur due to various reasons including SMTP configuration problems, template errors, recipient validation issues, or network connectivity problems. This guide provides comprehensive debugging tools and techniques. +{{< alert title="Which mail server is this guide about?" type="info" >}} +This guide covers the **deployment-wide** mail server - the one configured by +the four `SMTP_*` values, which carries mail for every organization by default, +including sign-up verification and password-recovery codes. + +An individual organization can instead register **its own** outbound mail +server, on the **Email** tab of Edit Organization. Where one is configured and +delivering, mail for that organization's members leaves through it and from its +own address rather than through the server described here - so when you are +diagnosing mail for one organization, check that tab before reaching for the +`SMTP_*` values. See +[Configuring your own mail server]({{< ref "cloud/guides/organizations/org-management/_index.md" >}}#configuring-your-own-mail-server). +{{< /alert >}} + ## Debug Log Levels To enable email debugging, set the `LOG_LEVEL` environment variable to `5` (Debug) or `6` (Trace): @@ -121,10 +135,12 @@ curl -X POST "https://cloud.layer5.io/api/system/email/test" \ ``` **Expected Response (Error - Email Configuration):** -```json -{ - "error": "Email configuration validation failed: SMTP authentication failed" -} + +This path answers **plain text**, not JSON - it is written with `http.Error`, +so there is no `{"error": ...}` envelope to parse: + +```text +Email configuration validation failed: SMTP authentication was refused by the mail server ``` ### 3. Required Environment Variables @@ -200,7 +216,12 @@ Flow emails (registration, password recovery, etc.) use a separate logging mecha ### 2. Authentication Failures -**Issue:** `SMTP authentication failed for user 'sender@domain.com'` +**Issue:** `SMTP authentication was refused by the mail server` + +The refused username and the mail server endpoint are deliberately **not** in +that message - an SMTP username is an email address, so both are written to the +log instead, as `authenticating as at `. Read the server +log rather than the response when you need to know which identity was refused. **Solution:** - Verify SMTP username and password are correct @@ -224,6 +245,12 @@ Flow emails (registration, password recovery, etc.) use a separate logging mecha - Verify email addresses are valid and properly formatted - Check for empty recipient lists - Validate email addresses contain `@` symbol +- Check for a carriage return or line feed inside an address. Those are refused + rather than cleaned: a line break in a recipient or `Cc` value would end the + header and start a new one, so an address carrying one is rejected outright. + Subject lines are treated differently - a line break there is collapsed to a + space rather than refused, which is why a delivered subject can be a single + trimmed line where its template spanned several. ### 5. Network Connectivity Issues @@ -247,11 +274,11 @@ INFO Development mode - Email details recipients=user@example.com subject="Test | Error Code | Description | Common Causes | |------------|-------------|---------------| | meshery_cloud-1092 | Failed to send email | Network issues, SMTP server down | -| meshery_cloud-1144 | SMTP authentication failed | Invalid credentials | +| meshery_cloud-1144 | SMTP authentication was refused by the mail server | Invalid credentials. The refused username and endpoint reach the log only, never the response | | meshery_cloud-1145 | SMTP send mail error | Server rejection, quota exceeded | | meshery_cloud-1146 | SMTP configuration error | Missing environment variables | | meshery_cloud-1147 | Email template missing | Template files not found | -| meshery_cloud-1148 | Email recipient validation failed | Invalid email addresses | +| meshery_cloud-1148 | Email recipient validation failed | Invalid email addresses, including any address containing a carriage return or line feed - those are refused outright, because a line break in a recipient would split the header block | ## Monitoring and Alerting diff --git a/content/en/cloud/guides/self-hosted/white-labeling/_index.md b/content/en/cloud/guides/self-hosted/white-labeling/_index.md index 825a0f1b9666..359d4c5cd005 100644 --- a/content/en/cloud/guides/self-hosted/white-labeling/_index.md +++ b/content/en/cloud/guides/self-hosted/white-labeling/_index.md @@ -98,6 +98,14 @@ On the [Organizations page](https://cloud.layer5.io/identity/organizations), you White-labeling extends past the browser: the footer shared by every transactional email Layer5 Cloud sends - invitations, welcome mail, role changes, catalog publish decisions, design comment mentions, email verification and password recovery codes - is built from your organization's own contact information rather than Layer5's. +That covers what the message *says*. The address it arrives *from* is a separate +setting: by default every message leaves through Layer5's shared mail server, so +a fully branded email still arrives from a Layer5 address. To change that too - +so mail for your members is delivered by your own server, from your own domain, +and aligns with your SPF and DMARC policy - register a mail server on the +**Email** tab of Edit Organization. See +[Configuring your own mail server]({{< ref "cloud/guides/organizations/org-management/_index.md" >}}#configuring-your-own-mail-server). + The same five link fields drive both your sign-in pages and your email footers. Set them as an [Organization Administrator]({{< ref "cloud/concepts/identity-and-security/roles/organization-roles.md" >}}) on the [Organizations page](https://cloud.layer5.io/identity/organizations): click the pencil icon next to your organization name, then fill in the fields under **Login page links**. | Field | Where it appears in email |