sp-imap

Generic IMAP issue provider plugin for Super Productivity.

Works with Gmail, Outlook, Fastmail, iCloud Mail, and any standard IMAP server — no companion server needed. Uses SP's nodeExecution permission to connect to IMAP directly from within the Electron desktop app.

Requires the SP desktop app. The nodeExecution permission is only available in the Electron build, not web/PWA.

How it works

Super Productivity ←──HTTP──→ sp-imap-bridge ←──IMAP──→ Email server
      (plugin)                 (localhost:9876)

The bridge runs locally and connects to your IMAP account. The SP plugin talks to the bridge — no IMAP credentials ever enter SP.

Features

• Any IMAP provider — Gmail, Outlook, Fastmail, iCloud, self-hosted
• Folder-based inbox — monitor any IMAP folder or label
• Backlog import — pull all unread emails from the folder into SP
• Search 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 / moves / marks read / deletes the email

Setup

Step 1 — Install and start sp-imap-bridge

See sp-imap-bridge for full setup.

Quick start:

npm install -g sp-imap-bridge
# Create ~/.sp-imap-bridge/config.json with your IMAP credentials + API key
sp-imap-bridge

Step 2 — Install the SP plugin

1. Download imap-issue-provider.zip from Releases
2. In SP → Settings → Plugins → Install from ZIP

Step 3 — Add a provider instance

1. SP → Settings → Issue Providers → Add Provider → IMAP Email
2. Fill in:

Field	Value
Bridge URL	http://localhost:9876
API Key	The key from your bridge config
Folder	IMAP folder to monitor (e.g. sp-tasks, INBOX)
When done	Archive / Move / Mark read / Delete / Nothing

3. Click Test Connection — should return OK

Sync reference

SP field	IMAP/Email field	Direction
isDone	Archived / moved / read / deleted	Push (on done)
title	Subject	Pull only
notes	Plain text body	Pull only

Development

npm install
npm run build        # compile → plugin/plugin.js
npm run build:watch  # watch mode
npm run typecheck    # type-check only
npm run zip          # package → imap-issue-provider.zip

Project structure

sp-imap/
├── src/
│   ├── plugin.ts          # TypeScript source
│   └── plugin-api.d.ts    # SP plugin API types
├── plugin/                # Distributable
│   ├── manifest.json
│   ├── plugin.js
│   └── icon.svg
├── scripts/
│   └── sync-version.js
├── package.json
└── tsconfig.json