Setting Up Gmail with Kanmail

Kanmail connects to Gmail and Google Workspace accounts and turns your labels into a kanban board. There are two ways to connect; the first is recommended for almost everyone.

Option A - Sign in with Google (recommended)

This uses OAuth 2.0, so Kanmail never sees or stores your Google password.

  1. In Kanmail, add a new account and choose Sign in with Google.
  2. Your browser opens Google’s own sign-in page. Sign in and review the permissions.
  3. Approve access. Kanmail receives a limited-scope token that only permits email operations — it can’t touch anything else on your Google account.
  4. You’re returned to Kanmail and your Gmail loads.

Your token is stored securely in your operating system’s credential store. No app passwords, no IMAP settings to configure.

Option B - Manual setup with an app password

Use this only if you can’t use “Sign in with Google” (for example, certain restricted Workspace accounts). Requirements:

  1. Enable 2-factor authentication on your Google account (required to create app passwords).
  2. Generate an app password in your Google account security settings — see Google’s documentation.
  3. Check IMAP is available. On personal Gmail accounts it’s always on; Google removed the setting in January 2025. On Google Workspace accounts, your administrator controls it.
  4. In Kanmail, add the account manually using your address and the app password.

How Gmail labels work in Kanmail

Gmail uses labels, not folders, so a single email can carry several at once, and Kanmail shows it in every column whose label it has. Copy mode decides what happens when you drag a card out of the Inbox into one of your columns: with it on, Kanmail adds the column’s label and the email keeps its Inbox label too, exactly as Gmail labels intend. On the board it only appears in the column you dragged it to, but Gmail on the web and on your phone will still show it in the inbox until you archive it. Dragging between your own columns, or to Archive or Trash, is always a real move.

Copy mode is the Copy (not move) emails out of the inbox? checkbox in the account’s settings, under Advanced on the Mailboxes tab. It’s on by default for @gmail.com addresses and off for everything else, including Google Workspace accounts on your own domain. Turn it on for a Workspace account if you want the same label-style behaviour, or off if you’d rather a drag took mail out of the inbox everywhere. Kanmail also preserves Gmail-style search, so searching works the way you’re used to.

Turning labels into columns

Once connected, pick which Gmail labels appear as columns on your board — for example Inbox, Needs Reply, Waiting, plus any custom labels you use. Drag emails between columns to re-label them. See Boards & Columns.

Troubleshooting