You opened Settings and the mail client is still empty
You just finished setting up Fedora Workstation. The desktop looks clean, the terminal is ready, and you open your mail client to check work email. The app asks you to add an account, but instead of asking for IMAP and SMTP servers, it points you to GNOME Online Accounts. You click through, grant permissions, and nothing happens in your mail client. Or worse, the OAuth window hangs on a corporate login page. You need your email synced without wrestling with manual server settings.
What GNOME Online Accounts actually does
GNOME Online Accounts is not a mail client. It is a D-Bus service that handles authentication and token storage for cloud providers. When you add Google, Microsoft, or Yahoo, the service negotiates an OAuth2 handshake, caches the refresh token, and exposes the account to GNOME applications via a shared interface. Evolution reads that interface and builds the IMAP and SMTP connection automatically. Thunderbird can use it too, but it requires a bridge extension. The system keeps your credentials out of plain-text config files. It also means you cannot add a random ISP mail server or a self-hosted Dovecot instance through this panel. GOA only speaks to providers with official OAuth2 endpoints.
Think of GOA as a credential vault with a standardized door. Applications do not ask for your password. They ask the vault for a temporary access token. The vault handles the refresh cycle behind the scenes. This design prevents password sprawl across multiple config directories and aligns with modern cloud security requirements.
Run the settings panel before you touch the terminal. The GUI handles the OAuth handshake correctly every time.
Add the account and expose it to your mail client
Open the Activities overview and type Online Accounts. The settings panel launches directly to the authentication section. Click the icon for your provider. A browser window opens and requests your credentials. Complete the login flow and approve the requested scopes. The browser closes and returns to the settings panel. Toggle the Mail switch to On. The panel saves the token and registers the account on the session bus.
If you prefer verifying the stored configuration, you can read the dconf database directly. The GUI writes to the same backend, so terminal inspection is safe and reversible.
Here is how to check whether GOA registered the account and which services are enabled.
# Query the dconf database for the GOA schema
dconf dump /org/gnome/online-accounts/ | grep -A 5 "mail"
# -A 5 prints the matched line plus five following lines
# This shows the account UUID and enabled service flags
# The output confirms whether the Mail toggle is actually persisted
The output will list a UUID block with mail=true or mail=false. If the flag is false, the mail client will not see the account. Toggle it again in the GUI and run the command once more. The database updates immediately.
Check the toggle before you open Evolution. A disabled service flag is the most common reason for a silent failure.
Verify the token and connection
Open Evolution or your configured mail client. The account should appear in the left pane with a green status indicator. Send a test message to yourself. Check the Sent folder and the Inbox. If the message routes correctly, the OAuth token is valid and the IMAP/SMTP bridge is active.
When the connection drops or the client shows a red error icon, the token may have expired or the D-Bus session lost the service registration. You can inspect the user journal for the exact failure point.
Here is how to pull the relevant logs without drowning in unrelated system noise.
# Filter the user journal for the GOA service and jump to the end
journalctl --user -xeu gnome-online-accounts.service
# --user targets the per-user session bus instead of the system bus
# -x adds explanatory hints for common systemd errors
# -e jumps to the tail so you see the latest authentication attempt
Look for lines containing oauth2, token refresh, or bus error. If you see GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown, the GOA daemon crashed and needs a session restart. Log out and back in. The session bus rebuilds the service registry automatically.
Read the journal before you reinstall packages. Most token failures are session state issues, not broken binaries.
Common pitfalls and what the error looks like
Corporate accounts often require SSO redirects that break inside the embedded OAuth widget. The browser window spins and eventually prints Error: Authentication cancelled by user. This is not a network failure. The corporate identity provider blocks embedded login flows for security. Open the provider's website in your regular browser, complete the login, then return to GNOME Online Accounts and click the provider icon again. The cached session often bypasses the redirect loop.
Legacy email providers that still use basic IMAP/SMTP authentication will not work here. GOA does not support username/password handshakes. You will see Error: Provider does not support OAuth2 in the journal. Use manual account setup in your mail client instead.
SELinux denials occasionally surface when third-party mail clients try to read the GOA D-Bus interface. You will see type=AVC msg=audit(...): avc: denied { read } for name="org.gnome.OnlineAccounts" in journalctl -t setroubleshoot. Do not disable SELinux. Install the setroubleshoot-server package if it is missing, then run sealert -a /var/log/audit/audit.log to generate a policy fix. Most modern clients ship with the correct SELinux context. The denial usually means you are running an outdated or manually compiled binary.
App passwords are required when two-factor authentication is enabled on the provider side. The OAuth flow will reject your standard password and print Error: Invalid grant: access_denied. Generate an app-specific password in your provider's security settings and use that during the initial handshake.
Trust the package manager. Manual file edits drift, snapshots stay.
When to use this vs alternatives
Use GNOME Online Accounts when you want a single place to manage cloud credentials for mail, contacts, and calendars. Use manual IMAP and SMTP configuration when your provider does not support OAuth2 or when you are connecting to a self-hosted mail server. Use Evolution directly when you need advanced folder management, server-side filtering, or PGP integration that GOA does not expose. Stay on the default Workstation setup if you only need basic email sync and want the system to handle token refresh automatically.