You are likely here because MailMate failed to access your email account and now you need to figure out why. This page describes various common issues and it provides some suggestions to help you resolve the issue. If this does not help then you might need the contact page. Feedback is also welcome if you find that something here is incorrect or missing.
General advice
First, you need to determine if the problem is a connection issue or a login (authentication) issue. If you have not seen a password requester or an authentication browser window (OAuth) then the problem is most likely a connection issue.
If you see a password requester then MailMate either did not have a password for the account or it failed when trying to use it. In the latter case, MailMate should inform you about the exact response from the server. Make sure you have used the correct password. Using the “Keychain Access” utility, you can review all passwords saved by MailMate (if you have allowed saving them).
Some email providers require/allow 2FA (two-factor authentication) or 2SV (two-step verification). This is often combined with a requirement to use so-called “app-specific passwords”. This means that you need to explicitly generate a password to be used with MailMate. How/where to do this depends on the email provider. Various specific providers are discussed further below.
Note: Currently, IMAP and SMTP require separate password settings in MailMate. In practice, these passwords are most likely to be the same and it might be confusing that MailMate asks for the password twice (once when synchronizing an account and once when sending the first email).
OAuth
A few email providers support a somewhat easier/safer way to log into an account known as OAuth (or OAuth 2.0). This authentication method requires MailMate to be explicitly registered with each IMAP provider. Currently, MailMate is registered to be used with Fastmail, Gmail, Office365, and Yahoo. It is important to note that this also means that each IMAP provider has the power to revoke the MailMate registration at any time. If/when that happens then the details on each email provider given further below include notes on how to work around this – the best approach will depend on the provider involved.
It’s important to note that even though an existing MailMate registration with an email provider can be revoked, it’s not really possible to block MailMate from accessing an account. At least not without blocking access for all native (desktop/mobile) apps and scripts. This is because OAuth used with a desktop email client works in a way that does not allow it to keep its “identity” secret. If a single app works with OAuth then all other apps can, at least in theory, pretend to be that app. Most apps won’t allow that or would require you to compile it yourself (if open source), but even closed source apps (like MailMate) cannot prevent the user from “bridging” connections through a proxy. In fact, someone made that easy to do and shared it on GitHub. This could be a useful tool if there are no other options. Warning: Be very careful with any similar services offering you to “tunnel” your traffic through a third party website. This requires a lot of trust in this third party.
Note: OAuth settings are shared between IMAP and SMTP in MailMate. The tokens retrieved are always saved in the local (login) keychain and can be reviewed using “Keychain Access”. They are named like this:
com.freron.MailMate.*.oauth-token
com.freron.MailMate.*.oauth-refresh-token
com.freron.MailMate.*.oauth-expiry-date
If you want to reset the OAuth access for a specific account then you need to delete these files in “Keychain Access”. Disabling/Enabling OAuth within MailMate should have the same effect. Note that this does not revoke the given tokens server-side. Where to do this will depend on the specific email provider used.
Email provider details
iCloud / Apple
Apple requires an app-specific password when configuring an account in MailMate. How to do this is described on this support page. You can read about Apple consumer email addresses here.
The recommended IMAP/SMTP settings are provided on this support page. Note the subtle difference between the username to be used for IMAP vs SMTP.
Notes:
- Apple Mail itself does not require an app-specific password. It appears Apple Mail works similarly to OAuth-based solutions, but this is not available to third party email client developers.
Fastmail
MailMate supports OAuth for Fastmail accounts. Alternatively, Fastmail also supports app passwords.
Notes:
- Fastmail has ensured me that blocking MailMate from OAuth access is very unlikely to happen. It would only happen if there was some kind of security issue which could somehow be helped by doing so.
- Technical note: The Fastmail implementation of OAuth is the only one (of those working with MailMate) using refresh token rotation.
Gmail / Google Workspace
MailMate has had OAuth support for Gmail since 2015. This was done with some concerns about how this could be a problem in the future. In 2024, Google tightened the requirements for the OAuth verification process, but MailMate passed the external assessment required and the experience was described on the MailMate mailing list. At the same time, Google stated that this was going to be a yearly assessment. In 2025, the recertification was announced to be a paid service and it’s currently unlikely MailMate will go through this process. This is also discussed on the mailing list.
When/If Google revokes the MailMate assessment/verification then OAuth will no longer work by default. In practice, MailMate becomes an “unverified” application. That should still allow up to 100 users to authenticate using OAuth (while being warned about the unverified state), but that is far from sufficient for MailMate, especially considering that some individual users are likely to access a lot of Google accounts.
Fortunately, there are other solutions depending on your type of Gmail account:
- Simple solution (OAuth-based): Google Workspace (aka G Suite aka Google Apps) users should be able to have the admin of the account explicitly allow MailMate. This should mean that OAuth still works for the account.
- Simple solution (password-based): Free
@gmail.comaccounts do not have settings allowing the user to explicitly allow MailMate. Instead, you need an app specific password. This option is very well hidden though, but here is a direct link. Note that this requires 2SV to be enabled for the account. - Advanced solution (OAuth-based): It’s also possible to make your own app registration with Google and then use these credentials with MailMate using the
MmGmailOAuth2ClientIDandMmGmailOAuth2ClientSecrethidden preference values. - Advanced solution (OAuth-based): If everything else fails then there’s still the option of the proxy mentioned in the general OAuth section above.
Notes:
- To fully understand how Gmail works in an IMAP email client, you need to read this part of the manual.
Office365
Microsoft disabled what they define as basic authentication] which means they now only support OAuth for Office365 accounts. In most cases, this should work with MailMate.
Notes:
- The OAuth support should also work for email addresses with domains such as
@outlook.com,@hotmail.com,@msn.com, and@live.com. - In some cases, OAuth support will only work if the admin of the Microsoft account involved explicitly allows MailMate and/or allows IMAP/SMTP access. See the note on DavMail below as a possible workaround if this does not work. When IMAP/SMTP is allowed then there’s also the option of the proxy mentioned in the general OAuth section above.
- If only SMTP access fails then take a look on this Microsoft support page.
- Microsoft supports their own native Exchange protocol for email, but MailMate is IMAP-only. This is not going to change.
- The Microsoft IMAP implementation/proxy is a bit primitive/buggy. In particular, when using tags in MailMate they are NOT synchronized with the server. Tags are local-only and they are lost if resetting the local database. A proxy named DavMail exists for Exchange which should map categories to IMAP keywords.
- Microsoft appears to support app passwords if 2FV is enabled. Feedback is welcome on this if you are able to figure out how and if this works.
Yahoo
MailMate supports OAuth for Yahoo accounts, but Yahoo also supports app passwords if needed.
Connection issues
This type of issue is most often caused by a configuration issue (wrong hostname and/or port number) or network setup. It’s rarely related to MailMate. Consider the following before contacting support:
- Some connection issues are temporary. Your local connection or the server might be affected by some kind of network downtime.
- Network conditions can change when you change location. Are you sure you are not behind some kind of firewall at your current location?
- Your IMAP/SMTP settings might be incorrect. You could try to see if the same settings work in another email client.
If you know how to use a Terminal window (located in Applications/Utilities) then you can manually test connecting to a server like this:
openssl s_client -connect imap.fastmail.com:993
openssl s_client -connect smtp.fastmail.com:465
The above uses the preferred ports for IMAP and SMTP, but if you need to connect to 143 or 587 then you can do it like this:
openssl s_client -starttls imap -connect outlook.office365.com:143
openssl s_client -starttls smtp -connect outlook.office365.com:587
In both cases, a working connection will result in a lot of output. The last line should be the server telling you that it’s ready for input. You can close a successful connection by hitting ⌃D (Control-D).