Clarify SMTP TLS error and surface STARTTLS toggle (#34104)

[juan-fdz-hawa]

Related issue: Resolves #34104

When saving SMTP settings with SSL/TLS off, STARTTLS on, and SSL cert verification on, the test-email send produced an opaque Go cert error that gave users no actionable hint. The two TLS-related toggles also live on different settings cards with no cross-reference, which made the conflict hard to spot before hitting Save.

Checklist for submitter

If some of the following don't apply, delete the relevant line.

• Changes file added for user-visible changes in changes/, orbit/changes/ or ee/fleetd-chrome/changes.
  See Changes files for more information.

Testing

• Added/updated automated tests
• QA'd all new/changed functionality manually

Summary by CodeRabbit

• Bug Fixes
  • Replaced a cryptic SMTP error with a clear, prescriptive message when SSL/TLS is disabled but STARTTLS is enabled.
  • Added a tooltip to the SSL/TLS checkbox explaining the relationship with STARTTLS and where to change Advanced options.
• Tests
  • Added tests covering the STARTTLS failure scenario and the new tooltip behavior.

[codecov]

Codecov Report

❌ Patch coverage is 50.00000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.68%. Comparing base (3aac728) to head (53a22ce).
⚠️ Report is 17 commits behind head on main.

Files with missing lines	Patch %	Lines
server/service/service_appconfig.go	0.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             main   #44857    +/-   ##
========================================
  Coverage   66.68%   66.68%            
========================================
  Files        2664     2675    +11     
  Lines      214781   215540   +759     
  Branches     9882     9850    -32     
========================================
+ Hits       143224   143739   +515     
- Misses      58521    58720   +199     
- Partials    13036    13081    +45     

Flag	Coverage Δ
backend	68.56% <50.00%> (+<0.01%)	⬆️
frontend	54.33% <ø> (+0.09%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: a7a31412-8a13-42fa-8226-339726b57606

📥 Commits

Reviewing files that changed from the base of the PR and between 26a8345 and 53a22ce.

📒 Files selected for processing (6)

• changes/34104-smtp-starttls-error-message
• frontend/pages/admin/OrgSettingsPage/cards/Smtp/Smtp.tests.tsx
• frontend/pages/admin/OrgSettingsPage/cards/Smtp/Smtp.tsx
• server/mail/mail.go
• server/mail/mail_test.go
• server/service/service_appconfig.go

---

Walkthrough

Introduces a new exported error ErrSTARTTLSWithoutSSLTLS in server/mail, surfaces that error when STARTTLS is attempted while TLS/SSL is disabled, and updates sendTestEmail error handling to return the specific error. Adds a tooltip (labelTooltipContent) to the SSL/TLS checkbox in the SMTP settings UI explaining that STARTTLS must be disabled in Organization settings > Advanced options. Adds unit tests: frontend tests for the tooltip and server tests simulating STARTTLS failure scenarios. No public API signature changes beyond the new error variable.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title accurately summarizes the main change: clarifying the SMTP TLS error and surfacing the STARTTLS toggle with improved visibility through tooltips.
Description check	✅ Passed	Description is complete and well-structured: includes related issue link, explains the problem, describes the solution with image, and checks off the applicable checklist items.
Linked Issues check	✅ Passed	All requirements from issue #34104 are met: specific error message added, tooltip text implemented, frontend UI updated, backend error handling added, and tests cover the scenario.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to addressing issue #34104: error message clarification, UI tooltip, test coverage, and error handling in mail/service layers.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 34104-unclear-error-message-when-save-smtp-settings-fails-due-to-tls-error

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}