Connect Gmail

To connect Gmail to CoIsland you need your address and a Google app password. CoIsland reads your mail over IMAP (imap.gmail.com, port 993, TLS) straight from your Mac, with no CoIsland server, no Google sign-in screen and no app for an admin to approve on a personal account. The app password stays in your login Keychain. This page covers creating the app password, the connector form, the four Gmail monitor kinds with searches you can paste, and the errors you may meet.

What you need

• A Gmail address, or a Google Workspace address whose admin allows IMAP and app passwords.
• 2-Step Verification turned on for the account. Google offers app passwords only then.
• An app password: 16 letters Google shows once, in four groups of four.

Your Google password never goes into CoIsland, and would not work: Gmail refuses it over IMAP.

Create a Google app password

1. Turn on 2-Step Verification at myaccount.google.com › Security, with an authenticator app or your phone. An account that allows only security keys, or is in Advanced Protection, cannot create app passwords.
2. Open myaccount.google.com/apppasswords.
3. Name it after what it is for, such as CoIsland, and select Create.
4. Copy the 16 letters. Google does not show them again.

Changing your Google password revokes every app password. When that happens, checks fail with the password message listed in Troubleshooting; create a new one and add it as a new connector.

IMAP is always on for personal Gmail accounts. On Google Workspace, your admin decides: IMAP must be on for your account and allowed for any mail client, and 2-Step Verification must not be limited to security keys.

Connect Gmail in CoIsland

Open Settings › Connectors, click + at the top right (or Add Connector when you have none yet), and choose Gmail. The form has two groups, Account and Access:

Field	What to enter
Email	Your Gmail or Google Workspace address.
Connector name	What monitors call it, filled in from the address until you type your own: gmail_ana for ana@gmail.com. Letters, digits, _ and -.
App password	The 16 letters, with or without Google’s spaces.

Then click Test connector, which saves nothing. It connects to imap.gmail.com, checks the server is Gmail, signs in, finds All Mail (whatever its name in your language) and opens it read-only. A success reads Connected, with your address, Gmail or Google Workspace, and All Mail with its number of emails.

Click Add Connector. The address goes to ~/Library/Application Support/CoIsland/connectors.json, the app password to your login Keychain. The first Gmail connector becomes the default.

Choose what to watch: the four Gmail monitor kinds

Open Monitors, add a monitor and choose Gmail. Every kind searches All Mail with Gmail’s own search syntax, the one you type in Gmail’s search box, so Spam and Trash are left out unless your search asks for them. A new Gmail monitor checks every 2 minutes; you can pick from 30 seconds to 30 days, and 1 minute or more is kind to Gmail. A new-emails monitor’s first check records what already matches and raises nothing.

Unread mail

An email alerts when it starts matching. It is followed by Gmail’s message id, so a label change does not make it new, and an email you read and mark unread again stays quiet.

in:inbox is:unread

category:primary is:unread

Mail from people

Addresses or whole domains, one per line. Their unread emails in your inbox alert. A line that is not an address adds more search, such as has:attachment.

ana@acme.com
@acme-legal.com

Gmail search

Any Gmail search. Gmail also mails you what Google Drive, Calendar and Chat have to say, so a search covers them too:

Example	Search
Drive comments	from:comments-noreply@docs.google.com is:unread
Calendar invitations	filename:invite.ics is:unread
Missed Chat messages	from:chat-noreply@google.com is:unread
Important and unread	is:important is:unread
Starred	is:starred
A label	label:ops-alerts is:unread

Searches with quotes (subject:"weekly report") and accents (subject:réunion) work as in Gmail. When more than 100 emails match, the newest 100 are compared and a warning says how many matched.

Unread count

A search whose number of matches is what matters: it alerts when the count crosses a threshold, count > 20 by default, and again only after it has dropped back.

in:inbox is:unread

When a monitor fires, the notch opens for a few seconds with its sound. Each email shows its subject, then the sender’s name and its label; never its text, its recipients or its attachments. Click it to open the alert in CoIsland, where the email is shown with its sender, recipients, date, attachments’ names and body. Its images are blocked until you click Load Images, since images in emails are how senders see that you opened them. Open in Gmail opens the thread in your browser.

What CoIsland does with your mailbox

It only reads. A check signs in, opens All Mail with EXAMINE (read-only), runs UID SEARCH with your search and reads the newest emails’ headers with BODY.PEEK, which leaves them unread, then signs out. Opening an alert reads that one email the same way. CoIsland never marks an email read, moves, labels, deletes, replies or downloads an attachment. It keeps one connection per account at a time, of the 15 Gmail allows.

An app password opens the whole mailbox to whoever holds it, so it stays in your login Keychain and goes only to imap.gmail.com. To revoke it, delete it at myaccount.google.com/apppasswords.

What a Gmail monitor’s watch file looks like

Every monitor is a .sql file in ~/.coisland/watches, Gmail ones included. The -- kind: line names the Gmail kind, and the body is the search:

-- name: Drive comments
-- kind: gmail.search
-- connector: gmail_ana
-- every: 2m
-- alert: new-rows
-- sound: Glass

from:comments-noreply@docs.google.com is:unread

The kinds are gmail.unread, gmail.senders, gmail.search and gmail.count. title sets how an email reads in the notch, with columns such as {SUBJECT}, {FROM}, {FROM_ADDRESS} and {LABELS}. Changing the search, the kind or the connector starts a new baseline. Watch files lists every header key.

Troubleshooting Gmail connector errors

• Gmail refused the app password. Create a new one at myaccount.google.com/apppasswords (a password change revokes them). The app password is wrong, revoked, or was revoked by a password change.
• Gmail needs an app password, not your Google password. Turn on 2-Step Verification, then create one at myaccount.google.com/apppasswords. Your Google password was pasted, or 2-Step Verification is off.
• An app password is 16 letters, shown in four groups of four. What was pasted is not an app password.
• Your organization has turned off IMAP or app passwords. Ask your Google Workspace admin. Then Gmail’s own words. The admin settings are Security › 2-Step Verification (any method but “Only security key”) and Apps › Google Workspace › Gmail › End User Access (IMAP on, any mail client allowed).
• Gmail is busy with other mail apps; the next check will try again. Gmail allows 15 connections per account, shared by every mail app, or asked to slow down. CoIsland waits longer between checks until it clears.
• Gmail could not read this search: then Gmail’s words. Try the search in Gmail’s search box, then paste it back.
• Gmail did not list All Mail. In Gmail’s settings, under Labels, make sure All Mail is shown in IMAP.
• This email is no longer in Gmail (deleted, or in Trash or Spam). An alert’s email was deleted or moved after it alerted.

Common questions

Why an app password and not “Sign in with Google”?

Signing in with Google needs an app Google has reviewed for access to Gmail, a review that takes weeks and must be renewed. An app password needs nothing but your own account settings. CoIsland may add Google sign-in later.

Can CoIsland mark my emails as read?

No. It opens your mail read-only and reads with BODY.PEEK, so an email is still unread in Gmail after CoIsland alerted about it or showed it.

Does it work with Google Workspace?

Yes, when your admin allows IMAP for any mail client and app passwords (2-Step Verification not limited to security keys). If not, the connector test says so.

Can I watch Google Drive, Calendar or Chat?

Through the emails Google sends about them: comments and mentions on your documents, calendar invitations, missed chats. Use the Gmail search examples above.

Next: Getting started for the rest of the app.