Skip to content

Accounts and authentication

Jump to bottom
Allison Bayless edited this page Oct 19, 2026 · 3 revisions

Accounts and authentication

TideMail stores IMAP and SMTP passwords, AI API keys, and OAuth refresh tokens in the system keychain. It uses secret-tool on Linux and Keychain on macOS. When TideMail starts, it loads any blank password, API key, or refresh token from the keychain. Saving Settings moves loaded secrets into the keychain and clears them from the config file.

If secret-tool is unavailable on Linux, TideMail writes these secrets to ~/.config/tidemail/config.toml. Keep that file private. Windows has no keychain support yet, so it always stores these secrets in %USERPROFILE%\.config\tidemail\config.toml.

Find server settings

In the account manager (M), the email or login is the first form row. For a Custom account, enter an email address and move to the next row. TideMail looks for server settings in DNS SRV records, known MX providers, and the domain's HTTPS autoconfig file. Check the result before saving. Press Ctrl+L to look up again and replace the server settings.

Changing or clearing the address removes settings from its previous lookup. Server values you edited yourself stay in the form. See First run for the lookup order and the limits on accepted servers.

Account passwords

  • Gmail: Google Account → Security → App passwords (requires 2-Step Verification), or sign in with OAuth (below)
  • Outlook.com / Microsoft 365 / Exchange Online: OAuth only — pick the Outlook provider and sign in (below); Microsoft no longer accepts passwords here
  • Yahoo: Account Security → Generate app password
  • iCloud: Apple ID → Sign-In and Security → App-Specific Passwords
  • On-premises Exchange or any other server: Custom provider with your normal username and password (basic auth over TLS)

If you expose an app password, revoke it and create a new one.

Typing a password in a window of its own (optional). On the account form, press Alt+P on the Password row to enter the password in your desktop's native dialog (zenity or kdialog, whichever is installed) instead of the terminal field. The password never appears in a command line or log, and Cancel leaves the stored password unchanged. The dialog is not offered over SSH, without a display, or when neither program is installed; the terminal field always works.

Gmail currently requires an app password while Google approval is pending. Turn on 2-Step Verification, generate one at myaccount.google.com/apppasswords, then paste it into the password field in the account manager (M) and save with Ctrl+S.

Gmail OAuth sign-in

Google OAuth is temporarily unavailable while TideMail's Google app awaits approval. The account form and installer both call this out. Use a Google App Password instead; existing saved Gmail OAuth accounts are left unchanged.

Developers can preview the Gmail App Password-only account form without changing saved credentials:

go run . --disable-google-oauth

See Development flags for the behavior and other UI preview options.

Outlook OAuth sign-in

The Outlook provider covers Outlook.com, Hotmail/Live, and Microsoft 365 / Exchange Online mailboxes. Microsoft retired basic auth for all of these, so the account signs in with OAuth. TideMail uses Mozilla Thunderbird's shared public client ID, which is already consented for IMAP/SMTP and needs no verification.

  1. In the account manager, add an account with provider Outlook, leave the Auth row on OAuth, and press Ctrl+O.
  2. Thunderbird's client can't use the device-code flow, so TideMail copies a sign-in URL to your clipboard. Open it, sign in, and you'll land on an unreachable https://localhost page. Paste that page's URL (or the code= value from it) into the Code field and press Enter.
  3. Save with Ctrl+S. IMAP and SMTP authenticate with XOAUTH2.

To use your own Azure app registration instead (which enables the device-code flow — a short code you approve at microsoft.com/devicelogin), register a "Mobile and desktop" app with the offline_access, https://outlook.office.com/IMAP.AccessAsUser.All, and https://outlook.office.com/SMTP.Send delegated permissions, then set TIDEMAIL_MS_CLIENT_ID (or ms_client_id under [oauth]).

Microsoft 365 work/school tenants often disable IMAP entirely; an admin must run Set-CASMailbox -ImapEnabled $true for the mailbox.

On-premises Exchange Server

A self-hosted Exchange server (2016/2019/Subscription Edition) is not the Outlook provider — it does not authenticate against Microsoft's cloud. Use the Custom provider:

  • IMAP host: your Exchange server's hostname, port 993, TLS
  • SMTP host: the same server, port 587 (STARTTLS) or 465
  • Username: your login (often DOMAIN\user or your UPN)
  • Password: your normal mailbox password

On-premises Exchange still accepts basic auth over TLS — Microsoft only removed it from Exchange Online. TideMail speaks XOAUTH2 and PLAIN only, so it cannot connect to an on-prem server whose admin has disabled basic auth and requires NTLM or Kerberos (GSSAPI).

Source in TideMail at 9621bf2

Use TideMail

CLI and development

Clone this wiki locally