sp-gmail

Gmail issue provider plugin for Super Productivity.

Label an email in Gmail → it appears as an SP task. Mark the SP task done → the email is archived or the label is removed.

Features

• Label-based inbox — monitor any Gmail label (e.g. sp, @action, todo)
• Backlog import — pull all emails with the label into the SP backlog
• Search emails by subject or sender from the SP add-task bar
• Pull sync — subject → task title, body → task notes
• Push sync — marking SP task done archives the email or removes the label

Sync behaviour

SP field	Gmail field	Default direction
Done	Archived / label removed	Both
Title	Subject	Pull only
Notes	Body (plain text)	Pull only

Setup

1. Google Cloud project & OAuth credentials

1. Go to Google Cloud Console
2. Create a project → APIs & Services → Enable APIs → enable Gmail API
3. Credentials → Create Credentials → OAuth client ID → choose Desktop app
4. Copy the Client ID and Client Secret

2. Get a Refresh Token via OAuth Playground

1. Open Google OAuth Playground
2. Click the settings gear (top right) → Use your own OAuth credentials → enter your Client ID and Secret
3. In Step 1, scroll to Gmail API v1 and select https://www.googleapis.com/auth/gmail.modify
4. Click Authorize APIs and complete the consent screen
5. Click Exchange authorization code for tokens
6. Copy the Refresh token

3. Create the Gmail label

In Gmail, create a label (e.g. sp). Apply it to any emails you want to appear as SP tasks.

4. Install in Super Productivity

1. Download gmail-issue-provider.zip from Releases
2. In SP → Settings → Plugins → Install from ZIP → select the zip
3. Go to Settings → Issue Providers → Add Provider → choose Gmail
4. Fill in: Client ID, Client Secret, Refresh Token, Label name
5. Choose what happens when you mark a task done (archive, remove label, or nothing)
6. Click Test Connection → should succeed

Development

npm install
npm run build        # compile src/plugin.ts → plugin/plugin.js
npm run build:watch  # watch mode
npm run typecheck    # type-check without emitting
npm run zip          # package plugin/ into gmail-issue-provider.zip

Project structure

sp-gmail/
├── src/
│   ├── plugin.ts          # TypeScript source
│   └── plugin-api.d.ts    # SP plugin API type declarations
├── plugin/                # Distributable (load this in SP)
│   ├── manifest.json
│   ├── plugin.js
│   └── icon.svg
├── scripts/
│   └── sync-version.js    # Keeps manifest.json version in sync with package.json
├── package.json
├── tsconfig.json
└── README.md

Gmail API reference

• Messages.list
• Messages.get
• Messages.modify
• Labels.list