feat(settings): select Email Domain for custom email accounts #2850

artykbasar · 2025-12-31T02:18:12Z

Summary

Adds Email Domain support for Custom email accounts in Helpdesk Settings. You can now select an existing Email Domain while creating/editing a Custom account; selecting a domain auto-fills the IMAP/SMTP server, ports, and SSL-related fields. Domain creation/editing is delegated to Desk to avoid duplicating DocType UI inside Helpdesk.

What changed

UI (Helpdesk Settings → Email Accounts)

Custom provider now includes an Email Domain Link field.
Selecting a domain fetches the Email Domain doc and auto-populates:
- Incoming/Outgoing servers, ports, SSL flags, cert validation flags, sent folder settings, attachment limit, etc.
Create New from the Link field opens Desk in a new tab:
- /desk/email-domain/new-email-domain
Added Edit Domain button (only shown when a domain is selected):
- /desk/email-domain/<domain>
Added “Open in Desk” link for Email Account records in the edit view (convenience + escape hatch).
Custom provider icon falls back to the existing Lucide mail icon (no new assets).

Validation

For Custom accounts, validation now allows either:
- Domain selected, OR
- Manual server settings (email_server + incoming_port + smtp_server + smtp_port)

Backend (helpdesk/api/settings/email.py)

Adds service aliases for compatibility with Email Account “service” values, e.g.:
- Outlook.com, Yahoo Mail, Yandex.Mail (alongside existing labels)

Why

Previously, Custom-domain accounts configured via Desk could result in a broken/blank experience in Helpdesk Settings and were not manageable from the Helpdesk UI. This change makes Custom email accounts configurable in Helpdesk while still leveraging the canonical Desk DocTypes.

Manual testing

Create → Custom → select Email Domain → verify fields auto-fill → save.
Edit existing Custom account → change Email Domain → verify fields update.
Verify Frappe Mail still uses its API Key/Secret/Site flow (not Custom).
Verify Create/Edit Domain links open Desk in a new tab.

Issue

Fixes #2635

Helpdesk.custom.email.providermov.-.1080WebShareName.mov

RitvikSardana · 2026-01-01T15:55:25Z

@artykbasar
please add some screenshots.

artykbasar · 2026-01-01T17:55:16Z

@artykbasar please add some screenshots.

Helpdesk.custom.email.providermov.-.1080WebShareName.mov

artykbasar · 2026-01-07T18:18:00Z

@RitvikSardana I have done screen recording of the ui changes, I hope it will be easy to see. If you cannot see it, let me know I will upload screenshots as well.

RitvikSardana · 2026-01-13T05:14:11Z

Hello @artykbasar

Both SSL and TLS settings are available for both Incoming and Outgoing

Would suggest to add SSL and TLS After Incoming Port Field and label it as "Use SSL for Incoming"

similarly add these after "Outgoing" Port as well.

"Use SSL for Outgoing"

RitvikSardana · 2026-01-13T05:18:49Z

desk/src/components/Settings/EmailAdd.vue

 import EmailProviderIcon from "./EmailProviderIcon.vue";
 import { __ } from "@/translation";
 import SettingsLayoutBase from "@/components/layouts/SettingsLayoutBase.vue";
+import { Link } from "@/components";


Use Link component from frappe-ui

Will not need Clear button then

RitvikSardana · 2026-01-13T05:21:25Z

desk/src/components/Settings/EmailAdd.vue

 const { updateOnboardingStep } = useOnboarding("helpdesk");

-const state: Reactive<EmailAccount> = reactive({
+const state = reactive<EmailAccountFormState>({


Use different state variable instead of using the same for Custom Domains

A lot of unwanted data is sent to the backend in case of Gmail or some Popular Providers.

RitvikSardana · 2026-01-13T05:21:49Z

desk/src/components/Settings/EmailAdd.vue

 import SettingsLayoutBase from "@/components/layouts/SettingsLayoutBase.vue";
+import { Link } from "@/components";
+
+type EmailAccountFormState = {


Use different type which maybe can be extended from this

RitvikSardana · 2026-01-13T05:24:02Z

desk/src/components/Settings/EmailAdd.vue

+watch(
+  () => state.domain,
+  async (val) => {
+    if (!val) return;


can add another early return if email account selected is not Custom

RitvikSardana · 2026-01-13T05:25:36Z

desk/src/components/Settings/EmailEdit.vue

+              </span>
+              <span v-if="deskEditUrl" class="flex items-center gap-1">
+                <a :href="deskEditUrl" target="_blank" class="text-ink-blue-2 underline">
+                  {{ __('Open in Desk') }}


https://docs.frappe.io/erpnext/user/manual/en/email-domain

this link should be used

Read more about it

RitvikSardana · 2026-01-13T05:27:41Z

helpdesk/api/settings/email.py

        "use_ssl": 1,
        "smtp_server": "smtp-mail.outlook.com",
    },
+    "Outlook.com": {  # backwards-compatible alias


Please explain this with some context of backwards compatibility

Hi Ritvik — good question.

I added the Outlook.com / Yahoo Mail / Yandex.Mail entries because those exact strings are already used by Frappe’s Email Account DocType in Desk, and many existing installations can have Email Account records stored with those values in the service field.

In Helpdesk Settings UI we show the providers as Outlook, Yahoo, and Yandex. If someone already has an Email Account created in Desk with service = "Outlook.com" (for example), Helpdesk’s backend lookup (email_service_config.get(service)) won’t match it unless we handle that variant — which can lead to “service not supported” or missing defaults.

So these are simply aliases that treat those stored values the same as the equivalent provider, so older/existing records work smoothly.

If you prefer, I can update the inline comment to be more explicit, e.g.:

Alias for service values already stored by Desk/Email Account (Outlook.com, Yahoo Mail, Yandex.Mail).

RitvikSardana · 2026-01-13T05:28:13Z

Also pull latest changes
@artykbasar

- Add Email Domain link field for Custom provider and auto-fill server settings - Open Email Domain/Email Account in Desk for create/edit - Avoid sending Custom-domain fields for non-Custom providers - Add service aliases for legacy Email Account service values (e.g. Outlook.com, Yahoo Mail, Yandex.Mail)

artykbasar · 2026-01-13T20:37:31Z

Hi @RitvikSardana, thanks for the detailed review 🙏

I’ve addressed all the feedback and squashed the changes into a single clean commit (43038ecd9) for easier review.

Summary of updates

Reordered Incoming/Outgoing SSL/TLS fields with clearer labels as suggested.
Switched to the standard frappe-ui Link component for Email Domain selection.
Split common/provider state and Custom-domain state so non-Custom providers (Gmail, Outlook, etc.) don’t send unnecessary fields.
Refactored form state types into extendable base + provider + custom types.
Added explicit early returns in Email Domain watchers when provider isn’t Custom.
Updated the “Read more” link to the Email Domain documentation.
Clarified inline comments for service aliases to explain backwards compatibility with existing Desk Email Account records.

The branch is now rebased on latest develop, build/migrate succeeded locally, and the working tree is clean.

Please let me know if you’d like any further tweaks.

codecov · 2026-01-23T15:31:09Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 50.56%. Comparing base (4c73593) to head (d811720).
⚠️ Report is 78 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #2850      +/-   ##
===========================================
+ Coverage    50.54%   50.56%   +0.01%     
===========================================
  Files          122      122              
  Lines         5403     5403              
===========================================
+ Hits          2731     2732       +1     
+ Misses        2672     2671       -1

☔ 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.

RitvikSardana · 2026-02-09T11:32:07Z

Thank you so much for this feature @artykbasar 🙏🏻
It was highly requested!

RitvikSardana reviewed Jan 13, 2026

View reviewed changes

artykbasar force-pushed the feat/email-domain-desk-links-clean branch from a2a8044 to 43038ec Compare January 13, 2026 20:07

Merge branch 'frappe:develop' into feat/email-domain-desk-links-clean

f4b7224

RitvikSardana requested review from Copilot and removed request for Copilot January 23, 2026 15:26

artykbasar and others added 5 commits January 26, 2026 08:52

Merge branch 'frappe:develop' into feat/email-domain-desk-links-clean

c3d7ba0

Merge branch 'develop' into feat/email-domain-desk-links-clean

d6274a0

fix: remove service field in custom email account

1b4b0a3

chore: code cleanup

816a347

fix: api in email type

d811720

RitvikSardana merged commit d7633c8 into frappe:develop Feb 9, 2026
7 checks passed

feat(settings): select Email Domain for custom email accounts #2850

feat(settings): select Email Domain for custom email accounts #2850

Conversation

artykbasar commented Dec 31, 2025 • edited by RitvikSardana Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

UI (Helpdesk Settings → Email Accounts)

Validation

Backend (helpdesk/api/settings/email.py)

Why

Manual testing

Issue

Uh oh!

RitvikSardana commented Jan 1, 2026

Uh oh!

artykbasar commented Jan 1, 2026

Uh oh!

artykbasar commented Jan 7, 2026

Uh oh!

RitvikSardana commented Jan 13, 2026

Uh oh!

RitvikSardana Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

RitvikSardana Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

RitvikSardana Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

RitvikSardana Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

RitvikSardana Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

RitvikSardana Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

artykbasar Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

RitvikSardana commented Jan 13, 2026

Uh oh!

artykbasar commented Jan 13, 2026

Summary of updates

Uh oh!

codecov bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

RitvikSardana commented Feb 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

artykbasar commented Dec 31, 2025 •

edited by RitvikSardana

Loading

codecov bot commented Jan 23, 2026 •

edited

Loading