Mail Feishu

Name: Mail Feishu
Rating: 3.5 (1 reviews)
Author: larry-xue

By larry-xue 👁 22 views ▲ 0 votes

OpenClaw plugin: Gmail real-time notifications to Feishu/Lark via Google Pub/Sub

GitHub

Install

npm install &&

README

# openclaw-mail-feishu

OpenClaw plugin for real-time Gmail notifications to Feishu/Lark.

Uses Google Pub/Sub for instant delivery — no polling, no delay.

## For AI Agents

Copy the prompt below and send it to your AI agent to set up this plugin automatically.

```
Set up the openclaw-mail-feishu plugin. This plugin delivers real-time Gmail notifications to Feishu/Lark via Google Pub/Sub.

Before starting, ask me for: (1) my Gmail address, (2) my Feishu/Lark webhook URL — if I don't have one, guide me to create it: Feishu group → Settings → Bots → Add Bot → Custom Bot → copy webhook URL, (3) my Google Cloud project ID — if I don't have one, guide me to create one at https://console.cloud.google.com, (4) optionally an LLM API key for smart email filtering.

Then follow these steps in order:

Step 1 — Check prerequisites:
- gog CLI installed: run "which gog && gog --version". If missing, download from https://github.com/openclaw/gogcli/releases for the correct platform.
- gog Gmail auth: run "gog auth list". If no account, guide me through OAuth: I need a Google Cloud project with OAuth credentials (Desktop app type), then run "gog auth credentials /path/to/client_secret.json" and "gog auth add [email protected] --services gmail".
- OpenClaw running: run "openclaw status".

Step 2 — Enable Google Cloud APIs. Send me these two links to open in browser and click Enable:
- Gmail API: https://console.cloud.google.com/apis/library/gmail.googleapis.com?project=PROJECT_ID
- Pub/Sub API: https://console.cloud.google.com/apis/library/pubsub.googleapis.com?project=PROJECT_ID
Wait for me to confirm before proceeding.

Step 3 — Create Pub/Sub topic and subscription. If gcloud is available, run:
  gcloud pubsub topics create gmail-notifications
  gcloud pubsub subscriptions create gmail-notifications-sub --topic=gmail-notifications
  gcloud pubsub topics add-iam-policy-binding gmail-notifications --member="serviceAccount:[email protected]" --role="roles/pubsub.publisher"
If gcloud is NOT available, use REST API with an OAuth token that has pubsub scope:
  curl -X PUT "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/gmail-notifications" -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json"
  curl -X PUT "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/gmail-notifications-sub" -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"topic":"projects/PROJECT_ID/topics/gmail-notifications","ackDeadlineSeconds":60}'
  curl -X POST "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/gmail-notifications:setIamPolicy" -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"policy":{"bindings":[{"role":"roles/pubsub.publisher","members":["serviceAccount:[email protected]"]}]}}'

Step 4 — Install and configure the plugin:
  git clone https://github.com/larry-xue/openclaw-mail-feishu.git /tmp/openclaw-mail-feishu
  cd /tmp/openclaw-mail-feishu && npm install && npm run build
  openclaw plugins install /tmp/openclaw-mail-feishu
  openclaw plugins config mail-feishu --set gcpProject=PROJECT_ID
  openclaw plugins config mail-feishu --set pubsubSubscription=gmail-notifications-sub
  openclaw plugins config mail-feishu --set pubsubTopic=gmail-notifications
  openclaw plugins config mail-feishu --set feishuWebhook=WEBHOOK_URL
If LLM key was provided, also run:
  openclaw plugins config mail-feishu --set llmApiKey=KEY
  openclaw plugins config mail-feishu --set llmModel=gpt-4o-mini

Step 5 — Restart and verify:
  openclaw gateway restart
  sleep 3
  openclaw gateway logs | grep mail-feishu
Expected: "mail-feishu: watch registered" and "mail-feishu: watching inbox → feishu"

Step 6 — Test: ask me to send myself a test email. Within 30 seconds a Feishu card notification should appear.

Troubleshooting:
- "watch registration failed" → Gmail API not enabled or wrong project ID
- "subscription error" → Pub/Sub API not enabled or subscription name mismatch
- "feishu send failed" → webhook URL incorrect or bot removed from group
- No logs at all → plugin not loaded, check "openclaw plugins list"
```

---

## For Humans

[中文文档](README_CN.md)

## How It Works

```
Gmail inbox → Google Pub/Sub → OpenClaw plugin → LLM classification → Feishu/Lark webhook
```

1. Gmail pushes new email events to a Pub/Sub topic in real time
2. The plugin listens on the subscription and fetches email details
3. (Optional) LLM classifies urgency: 🔴 Critical / 🟠 Important / 🟡 Normal / 🟢 Low
4. Important emails are sent to Feishu/Lark as interactive card messages

## Features

- **Real-time** — Pub/Sub push, not IMAP polling
- **Feishu + Lark** — supports both `open.feishu.cn` and `open.larksuite.com` webhooks
- **Smart filtering** — optional LLM classification skips newsletters and spam
- **Rich cards** — sender, subject, summary, urgency tag in one card
- **Auto-renew** — Gmail watch is re-registered every 6 days automatically
- **Multilingual** — zh / en / ja notification and classification

## Prerequisites

- [OpenClaw](https://openclaw.ai) installed and running
- [gog CLI](https://github.com/openclaw/gogcli) with Gmail OAuth configured
- Google Cloud project with **Gmail API** and **Pub/Sub API** enabled
- Feishu/Lark group with a webhook bot

## Quick Start

### 1. Set up Google Cloud

```bash
# Create Pub/Sub topic and subscription
gcloud pubsub topics create gmail-notifications
gcloud pubsub subscriptions create gmail-notifications-sub \
  --topic=gmail-notifications

# Grant Gmail permission to publish
gcloud pubsub topics add-iam-policy-binding gmail-notifications \
  --member="serviceAccount:[email protected]" \
  --role="roles/pubsub.publisher"
```

Or do it via REST API / Google Cloud Console — see [Setup Guide](docs/setup.md).

### 2. Create Feishu Webhook

1. Open a Feishu group → Settings → Bots → Add Bot → Custom Bot
2. Copy the webhook URL (`https://open.feishu.cn/open-apis/bot/v2/hook/xxx`)
3. (Optional) Enable signature verification, note the secret

### 3. Install Plugin

```bash
# From source
git clone https://github.com/larry-xue/openclaw-mail-feishu.git
cd openclaw-mail-feishu
npm install && npm run build
openclaw plugins install .

# Or run the setup script
./scripts/setup.sh
```

### 4. Configure

```bash
openclaw plugins config mail-feishu --set gcpProject=YOUR_PROJECT_ID
openclaw plugins config mail-feishu --set pubsubSubscription=gmail-notifications-sub
openclaw plugins config mail-feishu --set feishuWebhook=https://open.feishu.cn/open-apis/bot/v2/hook/xxx

# Optional: webhook signature
openclaw plugins config mail-feishu --set feishuWebhookSecret=YOUR_SECRET

# Optional: LLM classification (without this, all inbox emails are forwarded)
openclaw plugins config mail-feishu --set llmApiKey=sk-xxx
openclaw plugins config mail-feishu --set llmModel=gpt-4o-mini
```

### 5. Restart & Verify

```bash
openclaw gateway restart
openclaw gateway logs | grep mail-feishu
# Expected: mail-feishu: watch registered, historyId=...
# Expected: mail-feishu: watching inbox → feishu
```

Send yourself a test email and wait a few seconds — you should see a Feishu card.

## Configuration Reference

| Key | Required | Default | Description |
|-----|----------|---------|-------------|
| `feishuWebhook` | ✅ | — | Feishu/Lark webhook URL |
| `feishuWebhookSecret` | — | — | Webhook signature secret |
| `gcpProject` | ✅ | — | Google Cloud project ID |
| `pubsubSubscription` | ✅ | `gmail-notifications-sub` | Pub/Sub subscription name |
| `pubsubTopic` | — | `gmail-notifications` | Pub/Sub topic name |
| `gogAccount` | — | gog default | Gmail account to watch |
| `credentialsPath` | — | ADC | Path to Google credentials JSON |
| `llmApiKey` | — | — | API key for classification LLM |
| `llmBaseUrl` | — | `https://api.openai.com/v1` | LLM API base URL |
| `llmModel` | — | `gpt-4o-mini` | LLM model name |
| `locale` | — | `zh` | Notification language (zh/en/ja) |

## Notification Card Preview

```
┌─────────────────────────────────┐
│ 📬 新邮件 — 🟠 重要              │
├─────────────────────────────────┤
│ 发件人        时间               │
│ Alice Chen    2026-05-29 14:30  │
│                                 │
│ 主题                            │
│ Q3 预算审批需要你签字              │
│ ─────────────────────────────── │
│ 摘要                            │
│ Alice 请你在周五前审批 Q3 预算     │
└─────────────────────────────────┘
```

## License

MIT

tools