Frequently Asked Questions

Connecting to Google Gmail

Google requires email applications implement its proprietary protocol to sign in to GMail by default. If you are running an up-to-date version of Geary, simply add your GMail account using the Online Accounts panel of GNOME Settings, and no further action needs to be taken by you.

If you do not have GNOME Settings and GNOME Online Accounts installed or are running an old version of Geary (earlier than version 0.13), then you will need to create an account using a standard IMAP login and password, after enabling this in your Google account. The setting to update depends on whether you have 2-Step authentication enabled for your Google account:

• If 2-step verification is enabled, you should create an App Password, and use that in your Geary account settings

• If 2-step verification is not enabled, you will need to allow access for “Less Secure Apps”

Connecting to Microsoft Exchange

To connect to a Microsoft Exchange server (Outlook.com, Office365, or local institution installations), the Exchange installation must have both its IMAP and SMTP "protocol connectors" enabled. These are enabled for Outlook.com and Office365, and hence Geary can connect to those services. There are no plans to support Microsoft's proprietary mail access protocols going forward. Thus if the IMAP connector is not enabled for your Exchange installation, please get in contact with your Exchange administrators and ask them to enable it.

When configuring an Exchange account in GNOME Online Accounts, IMAP or SMTP configuration information will not be provided to Geary by Online Accounts, and hence an IMAP account will also need to be configured for Geary to be able to access mail for the account.

Note that using Davmail to access mail on an Exchange server is not supported, since Davmail does not implement any modern IMAP extensions, several of which Geary requires. These extensions (such as IMAP IDLE and UIDPLUS) have been supported by most mail servers (including MS Exchange) since the late 2000's. Unless Davmail implements these extensions, it will continue to be unsupported. Instead of using Davmail, use Exchange's IMAP support instead - it is substantially better.

Flatpak support

The recommended way to install Geary is to install the Flatpak package from Flathub, however due to Flatpak being relatively new technology, there are a few limitations still. We have a list of current known limitations that is being worked on, if you are experiencing an issue that is not listed there, please report it.

Please see Flatpak's Desktop Integration documentation for technical information about integrating and configuring Flatpak apps to work with your desktop.

Custom themes and Flatpak

Typically, Flatpak applications only respect custom themes if the theme is also installed via Flatpak. If the theme is installed via some other means (for example, in /usr/share/themes, or ~/.themes) then Flatpak apps will not be able to access it because of the security provided by the Flatpak application sandbox. Being an email application, Geary is likely to experience attacks from malicious parties, so Geary's Flatpak sandbox is quite stringent.

If you are using a custom GTK theme and it is not being applied to Geary, check that your theme has been installed via Flatpak (run flatpak list in a Terminal) and that it matches the current version of the GNOME runtime that Geary is using. For example, Geary 3.34 will be using the GNOME 3.34 runtime, and hence the theme will also need to be available for 3.34. If not, install it, and Geary (and other Flatpak apps) will be able to start using it.

If your theme is not available for Flatpak, we recommend filing a bug with your theme's developer asking them to publish it on Flathub. In the mean time you can use a command like flatpak override --user --filesystem=~/.themes:ro org.gnome.Geary to poke a hole in Geary's sandbox to support it until they do.

User interface translations and spell-checking dictionaries in Flatpak

Flatpak consults your desktop language preferences for installing translations for Geary's user interface and dictionaries for spell checking. You can check your existing settings and change them via the Region & Language panel in GNOME Settings. You can also check the existing languages installed by Flatpak and add additional languages using the flatpak config command from a terminal window. After changing these, run flatpak update to install the extra translations and spell checking dictionaries.

Not running GNOME 3?

Geary is designed for the GNOME 3 desktop, and as such depends on a number of standard desktop services provided by GNOME by default. While it is possible to run Geary under other desktop environments such as KDE, XFCE, Mate, and so on, you may need to ensure that the services Geary depends on are installed and correctly configured for your desktop yourself.

With these services installed, Geary will use your desktop's standard settings to determine your user interface language, writing direction, notifications, date and time format, GTK+ theme, icon theme, proxy settings, and so on. Consult your desktop environment's user manual for help in setting these, and Geary will pick up any changes you make automatically.

The following is the list of services that Geary expects to be present and configured correctly when you log in:

Session bus

Your login session should start or make it possible to activate a D-Bus session bus so that Geary can communicate with other desktop services, including those listed below.

Desktop address book

Folks is used to access a desktop-wide address-book for saving and looking up preferred names, contact pictures, and email addresses. While Folks supports a number of different storage backends, the most common one is evolution-data-server and we recommend installing both. GNOME Contacts is recommended for managing the address book, and Geary provides a shortcut for launching Contacts for to add and edit the desktop address book

Single sign-on

Geary uses gnome-online-accounts to implement both OAuth2 authentication and single-sign-on for the GNOME desktop. You do not need to have gnome-online-accounts installed for Geary to work, however you will have to log in to GMail, Outlook.com and other services using a standard login and password. See the FAQ entry about GMail above for more information.

Spell checking

Enchant is used for spell-checking emails in the composer and works with a number of different spell checker programs. To enable spell checking, ensure a spell checker program such as GNU Aspell and appropriate dictionaries for it in your preferred languages are installed. See the Flatpak section above to install additional spell checking dictionaries for Flatpak installations.

Notifications

A notification daemon is required to display notifications of new messages on your desktop. Your desktop will likely already provide a notification daemon, if not you will need to install one yourself.

Password storage

An implementation of the XDG Secret Service API must be listening on D-Bus so that Geary can store and retrieve passwords in a safe manner. One such implementation of this is the GNOME Keyring daemon, which your desktop may already use. KDE is working on ksecretsservice for native KDE support.

TLS certificate pinning

The GCR library is used for pinning TLS certificate exceptions, which is particularly important for mail servers that use self-signed certificates. GCR in turn uses p11-kit for securely storing certificates, and this requires a writable PKCS#11 store configured, which could be provided by either software (e.g. GNOME Keyring daemon) or hardware (e.g. a smartcard).

Proxy support

Geary uses glib-networking for establishing connections to remote servers, which in turn uses libproxy for looking up proxy configuration. Ensure you have the correct libproxy plugin installed for your desktop.

Troubleshooting

Geary crashes when I run it. What I can do to help the developers?

If you can reproduce a crash, please check you are running the most recent version of Geary. If so, then get a stack trace and report the bug.

Thanks!

How do I access debug logging?

Launch the Geary Inspector by typing <Alt> + <Shift> + I. With the Inspector, you can view, search, copy to the clipboard and save to a file both debug logging and useful system information. Since Geary 3.38, the Inspector's logging pane has a sidebar that allows you to toggle showing log entries for specific accounts only and specific logging domains.

To save the debug logs, select the appropriate account and logging domains, then click the Save button. The saved logs will also include the system information requested for bug reports.

It's also possible to display debug logs from the command line using --debug. Specifying additional --log-* arguments will cause more detailed logging information to be output. Run geary --help (packaged) or flatpak run org.gnome.Geary --help to see supported options.

Under the Hood

Data storage locations

Geary uses three standard locations for storing data: configuration, cache and data. The location of each depends on if you are running Geary as a regular app or under Flatpak, and if you are running a release build (that is, when installed normally from your distribution or Flathub) or running a nightly or developement build (that is, when built from source code).

Regular releases:

Note here, ~ is short for your home directory, e.g. /home/mjog

Development and nightly builds:

See BUILDING.md in Geary's source code for more information about build profiles.

How do I backup Geary mail?

Geary’s configuration is stored in the configuration directory above, so backing up that directory will make a copy of Geary’s account information that can be restored later by moving it back into place.

The mail Geary pulls from your server(s) is stored in the data directory above. Since mail is retrieved from your mail server it is safe to not back up this directory, however if it is deleted then your mail will need to be re-downloaded again.

Composer and Conversation Viewer

The composer and conversation viewer uses WebKitGTK to edit and display email message bodies as HTML documents, even for plain text email. To inspect the HTML interactively, run Geary with -i/--inspector. Right-click on an email body to open the WebKit Inspector window.

You can customize the display of message bodies in the composer and conversations via CSS. Place your custom CSS in a file named user-style.css in the configuration directory, as above. If the file exists when Geary starts, it will be loaded and added to composer and message web views as a user stylesheet when displaying editing and message bodies. You can use the Inspector to look and experiment with the HTML and CSS.

Note that if you have the preference Always watch for new mail enabled, Geary may already be running when you log in. If so, use geary --quit first to see any changes to your CSS.

Notice: The default HTML and CSS Geary uses in these web views is an internal implementation detail, and may change without notice between releases. We recommend you use the user stylsheet to make minimal changes to message style, for example, inverting the foreground and background colours only.

General

How is “Geary” pronounced?

Geary is pronounced with a hard G. It should sound like the word “gear” followed by a long “e” sound.

For an audio example, visit this website.