EmailFlow

简体中文

EmailFlow is a lightweight Chromium/Edge extension plus local Python API for collecting email attachments, uploading selected materials, and submitting an edited review record to a Feishu/Lark Base table.

This clean edition is intentionally generic. It does not include organization-specific reply text, private document links, real table IDs, mailbox snapshots, or operating data.

What It Does

• Opens as a browser side panel.
• Collects attachment candidates from the currently opened webmail message.
• Lets the operator select which files should be uploaded.
• Uploads selected files to a configured Feishu/Lark Drive folder through lark-cli.
• Shows returned upload links or file tokens for manual copying.
• Writes an edited material record to a configured Feishu/Lark Base table.
• Checks duplicates by title and link before writing.
• Tracks the number of replies copied today, deduplicated by message hash.
• Lets each operator customize review outcomes, reply templates, and form fields in the side-panel settings.
• Can import field names from the configured Feishu/Lark Base table to bootstrap the editable form.

EmailFlow does not log into a mailbox, crawl messages in the background, bypass verification, or send replies automatically.

Project Structure

• extension/: Chromium/Edge side-panel extension.
• emailflow/api.py: local API served on 127.0.0.1:8765.
• emailflow/feishu_adapter.py: wrapper around lark-cli.
• emailflow/mail_extract.py: deterministic attachment/link helpers.
• emailflow/db.py: short-lived local SQLite cache.

Requirements

• Python 3.10+
• Chromium or Microsoft Edge
• lark-cli installed and authenticated for upload/write features
• Access to the target Feishu/Lark Drive folder and Base table

Setup

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[api]'
cp .env.example .env

Edit .env:

DATABASE_PATH=data/emailflow.db
EMAILFLOW_API_HOST=127.0.0.1
EMAILFLOW_API_PORT=8765
EMAILFLOW_LOCAL_RETENTION_DAYS=7
EMAILFLOW_OPERATOR_NAME=Operator

LARK_CLI_BIN=lark-cli
LARK_CLI_IDENTITY=user
LARK_REVIEW_BASE_TOKEN=
LARK_REVIEW_TABLE_ID=
LARK_FOLDER_TOKEN=

Run:

.venv/bin/python -m emailflow api-serve

Health check:

curl http://127.0.0.1:8765/health

Browser Extension

1. Open edge://extensions or chrome://extensions.
2. Enable developer mode.
3. Choose Load unpacked.
4. Select the extension/ directory.
5. Open a webmail message and use the side panel.

The extension currently targets 126 Webmail URLs in extension/manifest.json. Adjust host_permissions and the URL check in extension/popup.js if you want to use another webmail provider.

Customizing the Side Panel

Click the settings button next to the EmailFlow title to customize the clean workflow.

Review outcomes:

• Add, rename, or delete outcome options.
• Edit the reply template for each outcome.
• Use {{date}} in a reply template when you want a date input to appear for that outcome.

Form fields:

• Add, rename, or delete fields shown in the side panel.
• Set the matching Feishu/Lark field name for each field.
• Choose single-line text, multi-line text, or dropdown input.
• Choose whether the submitted value is written as plain text or a list.
• Mark one field as title duplicate key and one field as link duplicate key.
• Mark required fields; the write button stays disabled until required fields are filled.

Settings are stored only in the browser's local storage. They are not committed to this repository.

Use Import fields from Feishu in the settings panel to read field names from the configured Base table. Imported fields are only a local UI draft; you can delete or edit them before saving.

Feishu/Lark Configuration

LARK_REVIEW_BASE_TOKEN is the value after /base/ in a Base URL:

https://<tenant-domain>/base/<base_token>?table=<selected_block>

The table= query parameter is not always a real table ID. It may point to a dashboard or another selected block. Use:

lark-cli base +table-list \
  --base-token <base_token> \
  --as user \
  --format json

Pick the table that should receive material records and use its id as LARK_REVIEW_TABLE_ID.

LARK_FOLDER_TOKEN is the value after /drive/folder/ in a Drive folder URL:

https://<tenant-domain>/drive/folder/<folder_token>

Verify folder contents with:

lark-cli drive files list \
  --folder-token <folder_token> \
  --as user \
  --format json

On upload, EmailFlow first looks for a child folder named by the current year and month, such as 202608. If found, it uploads there. Otherwise, it uploads to the configured folder itself.

Target Table Fields

The target Base table should contain these fields:

• 标题
• 链接
• 截止/期待发布时间
• 来源
• 备注
• 类别

These are only the default clean-edition fields. You can replace them in the side-panel settings. The side panel writes the edited form values exactly as entered.

Local Data

The following paths are local-only and ignored by git:

• .env
• .venv/
• data/

Temporary upload files are deleted after successful upload. On API startup, records and failed upload leftovers older than EMAILFLOW_LOCAL_RETENTION_DAYS are removed.

Privacy

Do not commit real mailbox content, private links, Feishu/Lark tokens, API keys, downloaded attachments, browser profiles, or local databases.