mail_server_configurator_selection

Odoo 19 lets individual users send through their own Gmail or Outlook account instead of the company's shared SMTP server. The setting lives on the user's Preferences tab, and this widget is the control behind it. It extends the standard selection widget but replaces the interaction: choosing an option immediately saves the record, then calls action_setup_outgoing_mail_server on res.users, which returns the provider's setup action, typically the OAuth consent flow, and the widget runs it.

Once a provider other than default is selected and outgoing_mail_server_id is set, a second control appears: a Test Connection button that saves, calls action_test_outgoing_mail_server, and either runs the returned action or flips into a red Connection failed state with the server's error as a toast.

Per-user sending matters for deliverability and for trust: replies come from the address the customer expects, and one salesperson's misconfigured mailbox does not affect the rest of the company. The widget's job is to make that setup a two-click flow a non-technical user can finish alone, which is why it saves eagerly and pipes errors back as notifications instead of failing silently.

The design decision worth knowing about is the readonly rule. The widget compares the record's id against the logged-in user's id and renders plain text when they differ. That means even an administrator cannot drive another user's mailbox setup from the backend, which is deliberate: the OAuth consent has to come from the mailbox owner's own session. Plan your rollout accordingly, with instructions to users rather than an admin doing it for them.

The core pattern: user Preferences

<field name="outgoing_mail_server_id" invisible="1"/> <!-- Used by the mail_server_configurator_selection widget -->
<field name="outgoing_mail_server_type"
       nolabel="1"
       widget="mail_server_configurator_selection"
       invisible="not has_external_mail_server"/>

Both core usages ship this exact pair, including the source comment. The invisible companion field is not optional: the Test Connection button's visibility reads outgoing_mail_server_id from the record, and if the view does not load it the button never appears.

The widget keeps a local state value layered over the field value, with a getter that prefers the local one. The source comment explains why: it lets the displayed choice change without marking the field dirty, since the record is saved programmatically anyway. On error, the catch block restores the previous value into that local state and shows error.data.message as a danger notification, so a failed OAuth flow leaves the form consistent instead of stuck on a provider that never got configured.

Both RPC paths call this.props.record.model.root.save() first. That is the whole form saving, not just this field, so any other invalid required field on Preferences will block the mail server setup with a validation error that seems unrelated to the dropdown. It is the same whole-record save pattern we have documented on boolean_toggle and priority.

Odoo 20 is expected at Odoo Experience in Brussels, 24 to 26 September 2026. The development branch is unstable, so treat everything here as provisional; the page is re-verified after release.

The visible changes are internal: component state moves from useState to the new proxy API, and the template's FontAwesome icons swap to the oi set, data-icon="check" and data-icon="power" replacing fa-check and fa-plug. No option, behavior, or registration changes are visible. CSS that targets the old icon classes inside this control will stop matching.