Likelyread

likelyread

Gmail 用のオープンソースメール開封トラッキングツールです。送信したメールが開封されたタイミングを知らせ、各開封がカウントされた理由を説明し、キャンペーンを追跡するための小さなダッシュボードを提供します。

使い方は 2 通りあります。

• Likelyread Cloud は app.likelyread.com で利用できます。Chrome 拡張機能をインストールし、Google でサインインすれば準備完了です。無料プランに加え、Pro ではキャンペーン分析と全履歴を利用できます。docs/CLOUD.md をご覧ください。
• セルフホスト：Caddy の背後に FastAPI と SQLite を使った小さなサーバーを 1 台用意し、1 つのコマンドでインストールします。トークンは 1 つで、すべての機能を利用でき、VPS の外にデータが出ることはありません。手順は以下をご覧ください。

仕組み

1. トラッキングを有効にして Gmail で 送信 をクリックすると、拡張機能がメールに 1x1 の不可視画像（https://your-domain/p/<uuid>.gif）を追加し、サーバーにメールを登録します。送信がブロックされたり、遅延したりすることはありません。
2. 受信者のメールクライアントが画像を読み込むと、サーバーがアクセスを記録します。
3. アクセスは確認時に分類されます。
   • self：自分の作成画面のプレビュー、または送信済みメールを自分で表示した場合（拡張機能がサーバーに通知し、ブラウザー内のリクエストもブロックします）。
   • prefetch：Apple Mail Privacy Protection がメールの配信時に画像を読み込んだ場合（Apple のネットワークからの、ユーザーエージェントが Mozilla/5.0 のみのアクセス）。
   • open：それ以外すべて。

完全な仕様については SPEC.md をご覧ください。

セットアップ

ポート 80 と 443 が開いている、小規模な Linux サーバー（Ubuntu または Debian、RAM は 512 MB あれば十分）が必要です。

1. アドレスを決めます。 所有するドメインのサブドメインを使用します。たとえば t.yourcompany.com の場合、サーバーの IP を指す A レコードを追加します（Cloudflare では「DNS のみ」（灰色の雲）に設定してください）。ドメインをまだお持ちでない場合は、インストーラーで無料の <your-ip>.sslip.io アドレスを使って試すことができます。実際のメールには独自ドメインを使用してください。スパムフィルターからの信頼度が高く、サーバーを移転しても引き続き利用できます。

2. サーバー上で次のコマンドを実行します。

curl -fsSL https://raw.githubusercontent.com/Hugo-SEQUIER/likelyread/main/deploy/install.sh | sudo bash

必要に応じて Docker をインストールし、アドレスを尋ね、プライベートトークンを作成し、HTTPS 証明書を取得して、すべてを /opt/likelyread で起動します。最後に、セットアップリンクが表示されます。

https://t.yourcompany.com/#connect=<your token>

このリンクはパスワードと同じように扱ってください。sudo bash /opt/likelyread/deploy/install.sh --show-link を実行すればいつでも再表示でき、ダッシュボードの Connect にも表示されます。

3. 拡張機能を接続します。 Chrome 拡張機能をインストールし、設定を開いてセットアップリンクを貼り付け、保存をクリックします。Gmail でメールを作成すると、送信の横に赤い目のアイコンが表示され、トラッキングされることがわかります。

拡張機能は Chrome ウェブストアから入手できます。独自にビルドしたものを使う場合は、cd extension && npm install && npm run build を実行します。次に chrome://extensions で デベロッパー モードをオンにし、パッケージ化されていない拡張機能を読み込むをクリックして、extension/dist を選択します。

4. ダッシュボードを開きます。 ブラウザーでセットアップリンクを開くと、サインインできます。

プロビジョニングスクリプトから実行する場合など、対話形式を使わずにインストールするには、sudo bash install.sh --domain t.yourcompany.com --yes を実行します。サーバー上の別のアドレスですでに別のサービスがポート 443 を使用している場合は、--bind-ip <public IP> を追加します。すべてのオプションについては、install.sh --help をご覧ください。

git clone https://github.com/Hugo-SEQUIER/likelyread.git
cd likelyread/deploy
cp .env.example .env
# set DOMAIN=t.example.com and LIKELYREAD_TOKEN=$(openssl rand -hex 32)
docker compose up -d
curl https://t.example.com/healthz   # {"ok":true}

バックアップ

すべてのデータは /opt/likelyread/deploy/data/likelyread.db（手動セットアップの場合は deploy/data/）にあります。cron から安全にオンラインコピーを作成するには、次のようにします。

sqlite3 /path/to/deploy/data/likelyread.db ".backup '/backups/likelyread-$(date +%F).db'"

更新

インストールコマンドをもう一度実行します。アドレス、トークン、データはそのまま保持されます。

キャンペーンとダッシュボード

キャンペーンは、メールに付けるラベルです。

• 作成中： Gmail の送信ボタンの下にある赤い目の横のキャンペーン名をクリックし、キャンペーンを選ぶか、新しいキャンペーン名を入力します。選んだキャンペーンは、次のメールのデフォルトになります。ポップアップとオプションページでは、同じデフォルトを設定できます。
• 送信後： ダッシュボードの詳細ページでメールのキャンペーンを変更するか、「キャンペーン」タブでキャンペーン全体の名前を変更します。

ダッシュボード（https://your-domain/）には、次の項目があります。

• 概要： トラッキング対象のメール数、開封率、開封総数、過去7日間の開封数、初回開封までの時間の中央値、過去30日間の送信数と開封数のグラフ、時間帯別の開封数（送信時間の選択に便利です）、最新の開封。
• キャンペーン： キャンペーンごとの開封率、開封数、初回開封までの時間を並べて表示します。
• メール： 件名、宛先、キャンペーンで検索し、ステータスで絞り込めます。メールを開くと、すべてのアクセスについて、時刻、判定、その理由、ユーザーエージェント、IP を確認できます。
• 送信者： 送信元アドレスごとの送信者の健全性（下記参照）。
• From アドレス： 各メールには、送信元のアドレス（アカウントまたは送信元エイリアス）が記録されます。複数のアドレスを使うと、ダッシュボードに「From」列とアドレスのフィルターが表示されます。

開封率は、少なくとも1回開封されたメール数 / トラッキング対象のメール数を意味します。Apple のプリフェッチと、自分自身による閲覧はカウントされません。

送信者の健全性

送信元アドレスごとに、「送信者」タブには次の3項目が表示されます。

• 設定： アドレスのドメインにおける SPF、DKIM、DMARC の設定状況と、不足している場合の具体的な修正方法。Gmail と Yahoo では、すべての送信者に SPF または DKIM、メールを大量送信する送信者に DMARC が必要です。gmail.com などの大手プロバイダーのアドレスでは、何もする必要はありません。
• 送信ペース： 送信を始めたばかりのアドレスには、1日目はメール20通、以降は1日ごとに5通ずつ増やし、最大50通とする目安を表示します。この上限に達すると、Gmail の作成ウィンドウで目の横に 20/20 today と表示されます。あくまで目安であり、送信がブロックされることはありません。すでに毎日送信しているアドレスには、確立済みのアドレスにチェックを入れてください。
• 開封数： 過去7日間の開封率を、その前の4週間と比較します。開封率が急激に落ちる、またはまったく開封されない場合は、メールが迷惑メールに振り分けられ始めた最初の兆候です。

この機能がメールを送信したり、エンゲージメントを偽装したりすることはありません。DNS と、ご自身のトラッキングデータを読み取ります。エージェントも sender_health ツールまたは likelyread health --from [email protected] を使って同じデータを取得できます。

ダッシュボードは静的なページで、独自のデータを持ちません。トークンを使って認証済み API を読み取ります。無効にするには、DASHBOARD=false を設定してください。

AI エージェントやスクリプトから送信されたメール

AI エージェントは、インストール不要で MCP 経由で接続できます。 Likelyread のサーバーは、Cloud でもご自身のサーバーでも、すべて /mcp に MCP エンドポイントを備えています。ダッシュボードの「接続」ページを開き、エージェント用のセットアップ手順をコピーしてください。Claude Code 用のコマンド1つ、Cursor、VS Code、Codex などの MCP クライアント用の数行の設定、または Hermes などのエージェントが自分でセットアップするためのプロンプト（サーバーの追加、スキルのインストール、接続の確認）を利用できます。トークンも個別に表示されており、「表示」を押すまではマスクされています。Claude Code の場合：

claude mcp add --transport http --scope user likelyread https://app.likelyread.com/mcp --header "Authorization: Bearer <token>"

ご自身のサーバーでは、アドレスは https://your-domain/mcp、トークンは LIKELYREAD_TOKEN です（インストーラーがこのコマンドを表示します）。Likelyread Cloud では、「接続」ページの「エージェントトークンを作成」で、エージェント専用のトークンを作成できます。詳細は docs/CLOUD.md を参照してください。 Claude と ChatGPT は、トークンではなくサインインで Likelyread Cloud に接続します。 Connect ページで Add to Claude をクリックすると、Likelyread が入力された Claude の Add custom connector ダイアログが開きます。Add、続いて Connect をクリックし、Google でサインインして、Likelyread のページで Claude を承認します。claude.ai のほか、Claude のデスクトップアプリとモバイルアプリでも利用できます。ChatGPT では、アドレス https://app.likelyread.com/mcp と OAuth を使ってカスタム MCP サーバーを追加します。アプリは /mcp でのみ機能するトークンを取得し、1 時間ごとに更新します。トークンは Account に表示され、ここから接続を解除できます。Claude Code も同じ方法でサインインできます。--header を付けずにサーバーを追加し、/mcp を実行します。セルフホスト可能なサーバーではトークンは 1 つで、アカウントはありません。そのため、アプリは上記のトークンを使って接続します。

エージェントは以下のツールを使用できます。また、サーバーの指示によって Likelyread のルールが伝えられます。キャンペーンの追跡前に確認すること、安全な送信ペースを保つこと、「opened」と言い、「read」とは言わないこと、そして読み取った内容はデータとして扱い、指示として扱わないことです。

これらは API と同じコードを実行するため、プランと上限も同じです。Likelyread Cloud の Free プランでは、Pro ツールとフィルター、および 1 日あたりの上限はエラーになり、エージェントはそのエラーを読み取って伝えられます。ピクセル URL は PUBLIC_URL、またはセルフホスト可能なサーバーの場合は https://DOMAIN から取得されます。エージェントが呼び出したアドレスから取得されることはありません。そのため、サーバー自体で動作するエージェントでも、メールには公開アドレスが設定されます。ピクセルを読み込む側がユーザーエージェントを選ぶため、ツールはヒットのユーザーエージェントや IP を返しません。

MCP に対応していないエージェントとスクリプトの場合： Connect ページの Agents without MCP, and scripts セクションには、エージェントに貼り付ける手順が記載されています。手順に従って likelyread CLI とエージェントスキルをインストールし、同じトークンで接続します。skills/likelyread/SKILL.md がそのスキルです（Claude Code、Hermes、その他のエージェントで使われている、公開された SKILL.md 形式です）。フォルダーをエージェントのスキルディレクトリ（例：~/.claude/skills/likelyread/）にコピーすると、CLI のインストール、ピクセルの追加、送信の登録、開封の確認方法をエージェントが把握します。追跡すべきでない場合についても含まれています。MCP ツールを備えたエージェントには、代わりにそちらを使うよう伝えます。

スクリプト、cron ジョブ、AI エージェントなど、自身でメールを送信するものは、cli/ にある likelyread CLI を使用できます。依存関係のない単一の Python ファイルで、すべてのコマンドが JSON を出力します。

ln -s "$PWD/cli/likelyread.py" ~/.local/bin/likelyread
likelyread setup 'https://t.example.com/#connect=...'   # your setup link; saves ~/.config/likelyread/config.json (mode 600)

下書きを作成し、後で送信します：

likelyread pixel                                   # {"id", "url", "img"}: keep the id with the draft
likelyread html --raw --id ID --file body.txt      # plain text to an HTML part, pixel appended
# ... send multipart/alternative: the text part unchanged, the HTML part above ...
likelyread track --id ID --subject "..." --to [email protected] \
  --campaign "Q4 outreach" --from [email protected] --sent-at 1792251301849

--sent-at は Unix 秒、Unix ミリ秒（Gmail の internalDate）、または ISO 8601 形式を受け付けるため、照合作業中など、送信後に登録できます。送信時刻より前のヒットは下書きのプレビューとして扱われ、開封として数えられることはありません。結果は likelyread ls --campaign "Q4 outreach" --status opened、likelyread show ID、likelyread campaigns、likelyread stats で確認します。show は --full を追加しない限り、各ヒットのユーザーエージェントと IP を省略します。

誰が開封したかを把握したい場合は、受信者ごとにメールを 1 通ずつ送信してください。プレーンテキストのメールにはピクセルを含められないため、HTML パートを追加してください。

設定

すべての設定は deploy/.env にあります（.env.example を参照してください）。

既知の制限事項

「開封」とは、受信者側でトラッキング画像が読み込まれたことを意味します。すべての開封トラッカーが測定するのはこの動作です。Likelyread は自分自身による表示と Apple のプリフェッチを除外しますが、誰かがすべての文面を読んだことまでは証明できません。

プライバシーと法令

すべてのデータは VPS 上に保持されます。完全な IP アドレスは 30 日間（IP_DAYS）保存され、その後はネットワーク情報に短縮されます。STORE_IP=false と RETENTION_DAYS を設定すると、保存するデータを減らせます。

トラッキングピクセルには、EU の ePrivacy 規則と GDPR が適用されます。フランスでは、メールのトラッキングピクセルに関する CNIL の勧告（2026 年 3 月 12 日採択、2026 年 4 月 14 日公開）により、キャンペーンの分析や最適化を目的として開封を測定する場合、受信者の事前同意が必要とされています。これは B2B メールにも適用されます。例外は限定的で、認証のセキュリティと、受信者が希望したメールの配信到達性の追跡に限られます。このツールの使用方法と、必要な場合の同意取得については、利用者の責任となります。

開発

# server
cd server
python -m venv .venv && . .venv/bin/activate
pip install -r requirements-dev.txt
pytest -q
LIKELYREAD_TOKEN=devtoken0123456789 DB_PATH=./dev.db PUBLIC_URL=http://localhost:8000 uvicorn app:create_app --factory --reload
# an agent on this machine: claude mcp add --transport http likelyread http://localhost:8000/mcp --header "Authorization: Bearer devtoken0123456789"

# demo data for the dashboard (never on your real database)
python scripts/seed_demo.py ./demo.db

# extension
cd extension
npm install
npm test          # unit tests + compose tests against a fake Gmail DOM
npm run typecheck
npm run build     # outputs dist/
# end to end: real Chromium with the built extension, a fake Gmail on
# mail.google.com and a real server (send, campaign, sender, server down, bad token)
CHROME_PATH=/path/to/chrome PYTHON=../server/.venv/bin/python npm run e2e
# the built extension as Chrome lists it (name and version), with the e2e package:
# tests/extension-listing.e2e.ts and e2e.config.ts at the repository root
cd .. && npm install && npx e2e run tests/extension-listing.e2e.ts
# Likelyread Cloud's Connect and Account pages and an app's OAuth sign-in, against a local
# cloud with fake Google (needs server/.venv): e2e.cloud.config.ts and tests/cloud/
npx e2e run --config e2e.cloud.config.ts tests/cloud/connect-apps.e2e.ts

# agent CLI
cd cli
python -m pytest -q tests

ロードマップ

• v0.3：Gmail の送信済みリストとスレッドビューにステータスバッジを表示、メールごとの「追跡を停止」機能。
• v0.4：初回開封時の通知（ntfy、Telegram、Webhook）、オプトイン方式。
• v0.5：リンククリックの追跡。
• 将来：Gmail ウェブ、Firefox からの受信者ごとのピクセル。

ライセンス

MIT