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. Enable IMAP in Gmail settings (Gmail → Settings → Forwarding and POP/IMAP → Enable IMAP).
  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 — a single email can carry several at once. Kanmail respects this with copy mode: when you drag an email between columns, it can be copied rather than moved, so a message can live in multiple columns at the same time, exactly as Gmail labels intend.

Copy-on-drag is part of Kanmail’s advanced account settings. Leave it at the default unless you specifically want move-style behaviour. 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