Account Setup
IMAP
Adding a new account is done using the “File ▸ Add IMAP Account…” menu item. This will initially show you a simple “wizard” with a single email address field. Given one or more email addresses, it will offer to automatically search for IMAP and SMTP settings using various methods. If successful, you will then be able to add these accounts to MailMate. Search results and/or errors can be seen in the context senstive menu of each email address given. If you prefer to enter settings manually then this is still possible. In this case, you may find Apple’s lookup page helpful if you do not know the server settings. If you need to edit or delete an existing account then use “Mailbox ▸ Edit Source…” or “Mailbox ▸ Remove Source” after selecting the account under “Sources” in the mailbox list. You can also reorder your accounts under “Sources”. This ordering is used whenever MailMate needs to display a list of accounts.
The configurable values are as follows:
-
Description
The name used to reference the account in the interface, e.g., in the mailbox outline.
-
Full Name
The name you would like to use for outgoing messages.
-
Email Address(es)
A comma-separated list of email addresses used for the account. Note that you should only add the addresses which you often use for new messages. These addresses are shown in a popup in the composer window, but the popup also allows you to customize the address. When replying to a message, MailMate automatically tries to use the email address for which the original message was sent. This does not require the address to be explicitly declared in the settings, but it does require an “Address Pattern” as described below.
If needed, an alternative name can be assigned to each address. Here is an example: “address1@example.com, Other Name <address2@example.com>”. The first address would be paired with the full name specified for the account, but the other address would be paired with the explicitly given alternative name: “Other Name”.
-
Address Pattern
This is an advanced feature for users with many email aliases. It allows you to tell MailMate the format of email addresses used for the account without listing them explicitly. Using this information MailMate can analyze the headers of an incoming message and automatically derive an appropriate address to be used for the default “From” address in a reply. This is combined with the “Full Name” specified above. The value used for this option must be a so-called regular expression. Example values are:
Regular expression Description address1@example\.com|address2@example\.comAn explicit list of alternative addresses address[0-9]*@example\.comAny address with an arbitrary suffixed number such as address123@example.comusername\+.*@example\.orgAny address with an arbitrary plus-suffixed string such as username+private@example.orgmm-.*@freron\.comAny address with mm-prefixed such asmm-dummy@freron.com -
IMAP Server / User Name
These are the most important settings. In most cases you do not need to define the port and unless you have very good reasons to do so then you should not disable the requirement for SSL (encryption of data sent via the connection to the server). Read further below for more information about subscriptions.
-
SMTP Server / User Name
The settings used for outgoing messages. Multiple accounts are allowed to share the same SMTP server. Use
-as username to tell MailMate that you want to skip authentication (anonymous SMTP). This is not supported by most SMTP servers. -
Require SSL
This setting ensures that the connection to the server is encrypted. You must have very good reasons to disable this setting since an unencrypted connection is an easy target for man-in-the-middle attacks.
-
OAuth2
Some servers support an authentication scheme known as OAuth2. In short, this requires that the user logs into a website and explicitly allows MailMate to access the service. A special token is then returned which MailMate can use to authenticate when connecting to the server. Enabling OAuth2 in the settings only means that MailMate uses this authentication method if it’s available. Currently, this only works with Gmail and Office365 accounts. Use “Help ▸ Send Feedback” if you have access to a different server with OAuth2 support. Note that Microsoft often uses the term “Modern Authentication” to describe what, in practice, is OAuth2 authentication for IMAP/SMTP.
MailMate can also be told to recognize email addresses as belonging to the user while never using these addresses for any address headers. No GUI exists for this feature yet. You must manually add retiredAddressPattern to this file: ~/Library/Application Support/MailMate/Identities.plist.
Migration
If you are migrating from an email client with support for IMAP then the easiest way to migrate is to ensure that all of your messages are located on IMAP servers.
If you are migrating from a POP3 only email client then you can try the “File ▸ Import Messages…” menu item in MailMate. You are then asked to chooses files or folders to import, and you also need to specify an IMAP mailbox to be used as the root for the imported messages. MailMate imports the following:
- single messages in standard RFC822 format (
.eml,.msgd) - single messages in Apples extended standard RFC822 format (
.emlx) - messages within mbox files (
.mbox)
MailMate uses names of mbox files and names of folders in the hierarchy scanned to create a hierarchy of IMAP mailboxes.
Note that the file extensions noted above are currently hardcoded, i.e., MailMate ignores all other files.
Subscriptions
The IMAP standard includes the concept of mailbox subscriptions. In short, the server maintains a list of subscribed (and unsubscribed) mailboxes. If your IMAP account is part of a webmail client then you can also use this subscription state to avoid fetching all mailboxes available in the web based interface. This is particularly useful for handling Gmail.
MailMate goes one step further with respect to mailbox subscriptions and adds the concept of client-side subscriptions as opposed to the server-side subscriptions described above. Client-side subscriptions are maintained locally by MailMate. This has the advantage that you can can use MailMate for a selected set of mailboxes and still have other mailboxes appear in other email applications, or in MailMate itself on another machine. It can also be used for handling Gmail accounts as an alternative to server-side subscriptions. Currently, it is not possible to subscribe to a mailbox client-side if it is not subscribed server-side.
Note that some email clients do not (and cannot be configured to) respect server-side subscription states and simply synchronize all mailboxes in the personal namespace. Therefore you cannot unsubscribe a mailbox in MailMate and then expect it to work for all other email clients as well.
Account States
When you look under “SOURCES” in the mailbox list then you might see one or more accounts in a greyed out state. This means that the account is not online. When this happens then a state string is shown in parentheses. These should be interpreted as follows:
| State | Description |
|---|---|
| Offline | This should only happen if the account was explicitly taken offline by the user. You can take it online in the “Mailbox” menu. Individual mailboxes within an account can also be taken offline. |
| Disconnected | The system tells MailMate that the server is unreachable. This is not always correct and therefore MailMate is still going to occasionally try to connect. This mostly happens when there is a network issue or the machine is offline. |
| Unavailable | Similar to “Disconnected” but it’s not the system that claims the server is unreachable. MailMate will automatically try to reconnect later. |
| Failed | Some persistent issue with a response from the server has triggered the account (or possible just a single mailbox) to enter the “Failed” state. |
| Throttled | Some servers throttle traffic when a lot of bandwidth is used, especially when initially synchronizing an account. MailMate automatically waits a bit before continuing the synchronization. This works for accounts using the [THROTTLED] response code. Currently this only means Gmail. |
Whenever something is failing then the “Activity Viewer” (⌥⌘0) can be used to learn more. Logging is enabled whenever the window is open and the log of each connection can be viewed in the lower part of the window.
Synchronization Schedule
The “Mailbox” menu has a “Synchronization Schedule” submenu which can be used to tell MailMate when to synchronize the emails in a given mailbox. If a mailbox has not been configured to use a specific schedule then it uses the schedule of its parent mailbox. This also means that setting a schedule on the account itself works as a default for the entire account. The INBOX is special since it always defaults to using the “Connected” state.
| Schedule | Description |
|---|---|
| Connected | The connection to the mailbox is never closed and therefore new messages and other changes should be detected immediately (depending on server behavior). This is also known as IMAP IDLE. You should not have more than 2 or 3 mailboxes using this schedule in a given account. |
| Every … | MailMate checks the mailbox on a regular basis ranging from 5 minutes to 1 hour. |
| Manually | The mailbox is not checked on a regular basis. |
In any case, an IMAP mailbox is always synchronized when it’s selected or if there exists any client side changes which need to be synchronized with the server. The only way to prevent synchronization completely is to take the mailbox offline.
Gmail
MailMate aims to support all standards compliant IMAP servers and as many non-standard IMAP servers as possible. One of the non-standard IMAP servers is the one provided by [Gmail][] (Google’s free webmail service). Its name is Gimap. The following explains how Gmail works via IMAP and how MailMate handles it. You only really need to know the following if you use labels in Gmail like you would use tags in other applications. Otherwise, you just need to know that MailMate works well with Gmail.
The official IMAP email client instructions from Google can be found here. There’s also a technical page describing how Google thinks of Gimap as an extension of IMAP. The truth is that it is more like a replacement. It has to be emphasized that it does not behave like a standard IMAP server which is also why it has a special section in this manual.
“All Mail” and Gmail labels
MailMate encourages the use of a single mailbox for archiving messages (for each IMAP account). This concept is similar to the “All Mail” mailbox in Gmail, but unfortunately it is not quite the same thing. With MailMate, a message is not in the “Archive” mailbox unless it has been explicitly archived. With Gmail, a message is (almost) always in “All Mail” and is simply removed from the “Inbox” when it is archived. In other words, with Gmail, the same message can be in multiple IMAP mailboxes. This is even more apparent when using labels (or starring messages).
IMAP does not support the Gmail model. If a message needs to be in multiple mailboxes then it must be duplicated. Instead, IMAP supports so-called keywords (flags), but Google decided to not use these for labels. The main reasons (good or bad) are probably that IMAP keywords are/were not well supported by many email clients and that it would require users to manually setup smart mailboxes for all their Gmail labels. Google chose a different approach which can be best described as a hack.
Each label in Gmail becomes a real mailbox when accessing the messages via IMAP. Existing email clients do not expect this and the result is that each message is fetched multiple times, once for each of its labels. Even if not using labels, the problem persists since every message in Inbox, Sent Mail or Drafts are also located in All Mail. In MailMate it becomes even worse because of the special “All Messages” virtual mailbox which is going to include all the duplicates.
Fortunately, MailMate can work around this problem.
How to configure MailMate
If you click “Edit Subscriptions” in the IMAP account editor for a Gmail account then you might notice that “[Gmail]/Starred” and “[Gmail]/Important” are unsubscribed. It is important to keep it that way. The starred emails are equivalent to flagged emails. If you need the “Important” emails then you must setup a tag in MailMate to match the special \Important Gmail label.
The “[Gmail]/All Mail” mailbox might also be unsubscribed, but this is optional. If you don’t subscribe to it then there’s is likely going to be emails on the server which do not appear in MailMate. If you do subscribe to it then MailMate will do its best to only synchronize the emails which do not exist in any of your other Gmail mailboxes (in order to avoid duplicates in MailMate). It’ll also be used as your “Archive” mailbox when it is subscribed. Otherwise, a new mailbox named “[Gmail]/Archive” is created and used as the archive mailbox.
Here comes the important part. Gmail labels falls into two categories:
- A label used as a folder: This kind of label is just like a standard IMAP mailbox. Labelling a message in Gmail is equivalent to moving it to a mailbox in MailMate. This is how Gmail labels are handled in MailMate by default. For example, you might like to move a message from the Inbox to a mailbox named “Receipts”.
- A label used as a tag: This is equivalent to flagging/starring/tagging a message. The message is not moved, but it is marked in order to be more easily found when searching or to be part of some virtual mailbox. MailMate must explicitly be told about this kind of label in the Tags preferences pane.
If you go to the Tags preferences pane in MailMate (⌘,) then notice the “Gmail Label” column. This can be used to tell MailMate to consider some tag name to be equivalent to a specific Gmail label. This has the following consequences:
- It is no longer considered to be an IMAP mailbox and it’ll disappear from the list of mailboxes in MailMate. This is implicitly how synchronizing duplicates are avoided in MailMate.
- Whenever you tag an email in MailMate then its corresponding Gmail label is also applied. This means it’ll show up with this label in the Gmail web interface.
- Whenever a Gmail label is applied via webmail then MailMate detects it and makes sure it shows up with the corresponding tag.
- If moving a message to a non-Gmail IMAP server then it keeps its IMAP keyword and thereby its tag in MailMate.
The end result of all this is that Gmail accounts and IMAP accounts can nicely co-exist without MailMate becoming a Gmail email client instead of an IMAP email client. You must subscribe to “[Gmail]/All Mail” for this to work when the labelled emails do not exist in any other mailboxes.