FlowMail

FlowMail is a local-first OpenClaw plugin that turns business email into persistent workflows.

It uses:

• gog as the Gmail adapter
• a local JSON store for persistent state
• lightweight business case packs
• OpenClaw tools for sync, query, and case actions

Install from a local folder

openclaw plugins install ./packages/openclaw-flowmail

For a dev link instead of a copy:

openclaw plugins install -l ./packages/openclaw-flowmail

Restart the Gateway afterwards.

Requirements

• gog available on the Gateway host PATH
• a working Gmail account already usable from gog

Configure

FlowMail now has two setup modes.

Simplest local mode

If you only want local rules and local state, this is enough:

{
  "plugins": {
    "entries": {
      "openclaw-flowmail": {
        "enabled": true,
        "config": {
          "gmailAccount": "[email protected]",
          "workflow": "external_trade_order"
        }
      }
    }
  }
}

Simplest cloud-assisted mode

If you want FlowMail Cloud to review low-confidence threads, only add your FlowMail API key.

{
  "plugins": {
    "entries": {
      "openclaw-flowmail": {
        "enabled": true,
        "config": {
          "gmailAccount": "[email protected]",
          "workflow": "external_trade_order",
          "flowmailApiKey": "fm_xxx"
        }
      }
    }
  }
}

cloudApiBaseUrl defaults to https://flowmail.email, and the plugin now resolves the workspace automatically from your FlowMail API key.

Full config example

Add this under plugins.entries.openclaw-flowmail in ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "openclaw-flowmail": {
        "enabled": true,
        "config": {
          "gmailAccount": "[email protected]",
          "workflow": "external_trade_order",
          "syncQuery": "newer_than:30d -category:promotions -category:social -category:forums -category:updates",
          "maxThreads": 25,
          "pollIntervalMinutes": 10,
          "autoPoll": true,
          "cloudApiBaseUrl": "https://flowmail.email",
          "flowmailApiKey": "fm_xxx",
          "cloudClassificationMode": "low_confidence"
        }
      }
    }
  }
}

gmailAccount is no longer required just to install or enable the plugin, but it is required before flowmail_sync or background polling can read Gmail.

workflow is the preferred config field. casePackId still works for backward compatibility.

Advanced config

These fields still work if you need to tune the plugin manually, but they are no longer required for a basic release setup:

• syncQuery
• maxThreads
• pollIntervalMinutes
• gogPath
• listCommandTemplate
• threadCommandTemplate
• stateDir
• cloudApiBaseUrl
• cloudClassificationMode

gog command templates

The plugin shells out to configurable command templates so you can adapt it to the exact gog syntax you use.

Available template variables:

• {{gmailAccount}}
• {{syncQuery}}
• {{maxThreads}}
• {{threadId}}
• {{gogPath}}

Defaults:

• list:
  • gog gmail search "{{syncQuery}}" --account "{{gmailAccount}}" --max {{maxThreads}} --json
• thread detail:
  • gog gmail get "{{threadId}}" --account "{{gmailAccount}}" --json

If your local gog build differs, override those two templates in plugin config.

Tools

This plugin registers these tools:

• flowmail_status
• flowmail_sync
• flowmail_list_cases
• flowmail_get_case
• flowmail_list_stuck_cases
• flowmail_list_missing_documents
• flowmail_mark_handled
• flowmail_defer_case
• flowmail_dismiss_case
• flowmail_draft_reply

Local test

From the repo root:

npm run test:openclaw-flowmail

This runs the local plugin tests without needing a real Gmail account or a live cloud API.

Publish

Use the repo-level publish script so npm only uses a single isolated token for this package publish:

FLOWMAIL_NPM_TOKEN=npm_xxx npm run publish:openclaw-plugin

Notes:

• The token should be a granular npm token for @flowmail
• It needs package publish permission
• It should support bypassing npm write-action 2FA for CLI publishes
• This avoids relying on the local npm login state, which is less reliable on this machine

Current workflow packs

• external_trade_order
• saas_revenue_order

Notes

• This MVP uses local JSON persistence instead of SQLite to keep install friction low.
• gog is the mailbox adapter. The source of truth for case state is the plugin store, not Gmail labels.
• Gmail labels can be mirrored in a later version.
• Cloud classification is optional. If configured, FlowMail only sends low-confidence threads for remote case-pack review and status review, then falls back to local rules on any error.
• Cloud auth is now plugin-friendly: use one flowmailApiKey, and the server resolves the workspace plus enabled case modules from that token.