# Mail Studio セットアップガイド（完全版）

このガイド1本で、ゼロの状態から「自分のメール配信システムが本番で動く」ところまで到達できます。
上から順に進めてください。**Claude Code に手伝ってもらう場合も、Claude はこのファイルを読んで案内します。**

- 所要時間の目安: 約30〜60分（＋ドメインのDNS反映待ち 0.5〜24時間）
- 費用の目安: Cloudflare 無料枠 + Resend 無料枠（1日100通/月3,000通まで無料）で運用可。必要なのは**メール送信用の独自ドメイン代**（年1,000〜2,000円程度）のみ

---

## 全体の流れ（地図）

```
STEP 0  事前準備（Node.js / 各種アカウント）
STEP 1  システムをCloudflareにデプロイ（この時点で管理画面が使える・送信はテストモード）
STEP 2  Resendとドメインの設定（実際にメールを送れるようにする）
STEP 3  テスト配信 → 本番切替（DRY_RUN解除）
STEP 4  日常の使い方・運用
```

ポイント: **STEP 1 が終わった時点で管理画面はフルに触れます**（送信テストモードなので誤送信の心配ゼロ）。
Resend やドメインの用意（STEP 2）は後からで大丈夫です。

---

## ⚡ 最速ルート: セットアップウィザード

STEP 1 の内容（Cloudflare ログイン → データベース作成 → パスワード登録 → デプロイ）は、**1コマンドで自動実行できます**。

```bash
npm install
bash scripts/setup.sh
```

ウィザードが1つずつ質問するので、答えていくだけで完了します（約5分）。

- 何度でも実行できます。済んでいる工程は自動でスキップされます
- パスワードや API キーの入力は**画面に表示されず、ファイルにも保存されません**（Cloudflare の Secrets に直接保管されます）
- ウィザードを使っても `DRY_RUN=true` のままなので、実メールは送信されません
- **Windows の方**は Git Bash か WSL で実行してください

> ウィザードが途中で止まった場合や、何をしているか理解しながら進めたい場合は、このまま STEP 0 から手動で進めてください。**手動でも結果は同じです。**

---

## STEP 0. 事前準備

### 0-1. 必要なもの

| もの | 用途 | 費用 |
|---|---|---|
| Node.js 18以上 | セットアップ作業に使用 | 無料 |
| Cloudflare アカウント | システムの動作場所（サーバー代わり） | 無料枠でOK |
| Resend アカウント | メール送信サービス | 無料枠: 100通/日・3,000通/月 |
| 独自ドメイン | メールの送信元（例: mail@あなたのドメイン.com） | 年1,000〜2,000円程度 |

> **なぜ独自ドメインが必要？** Gmail などのフリーメールのアドレスは送信元にできません（なりすまし防止の業界ルール）。すでにお持ちのドメイン（自社サイト等）があればそれを使えます。

### 0-2. Node.js の確認・インストール

ターミナル（Mac: 「ターミナル」アプリ / Windows: PowerShell）で:

```bash
node -v
```

`v18.0.0` 以上が表示されればOK。表示されない場合は https://nodejs.org/ja から「LTS版」をインストールしてください。

### 0-3. 依存パッケージのインストール

このフォルダ（解凍した場所）でターミナルを開き:

```bash
npm install
```

### 0-4. （任意）動作確認

```bash
npm test        # 99件のテストが全部 PASS すればOK
```

---

## STEP 1. Cloudflare セットアップ & デプロイ

### 1-1. Cloudflare アカウント作成

1. https://dash.cloudflare.com/sign-up で無料アカウントを作成
2. メール認証を済ませる（クレジットカード不要）

### 1-2. ターミナルから Cloudflare にログイン

```bash
npx wrangler login
```

ブラウザが開くので「Allow」をクリック。ターミナルに `Successfully logged in` と出ればOK。

### 1-3. データベース（D1）を作成

```bash
npx wrangler d1 create mail_db
```

実行結果に **`database_id = "xxxxxxxx-xxxx-…"`** という行が表示されます。この ID をコピーしてください。

### 1-4. 設定ファイルに database_id を書き込む

`wrangler.jsonc` をテキストエディタで開き、次の行を書き換えます:

```jsonc
"database_id": "REPLACE_WITH_YOUR_D1_DATABASE_ID"
      ↓
"database_id": "（1-3でコピーしたID）"
```

### 1-5. データベースにテーブルを作成

```bash
npm run db:init:remote
```

### 1-6. パスワード類（シークレット）を登録

```bash
# 管理画面のログインパスワード（自分で決めた文字列を入力）
npx wrangler secret put ADMIN_PASSWORD

# セッション署名鍵（下のコマンドで生成したランダム文字列を貼り付け）
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
npx wrangler secret put SESSION_SECRET
```

> RESEND_API_KEY は STEP 2 で登録します（今はなくて大丈夫）。

### 1-7. デプロイ！

```bash
npm run deploy
```

成功すると `https://mail-delivery-system.＜あなたのID＞.workers.dev` のようなURLが表示されます。

### 1-8. 動作確認

1. 表示されたURLをブラウザで開く
2. 1-6 で決めた ADMIN_PASSWORD でログイン
3. ダッシュボードが表示されれば **STEP 1 完了！** 🎉

> 画面左下に **DRY_RUN** バッジが出ています。これが「送信テストモード」の印で、この状態では実際のメールは1通も送信されません。安心して触ってください。
> 毎分の自動配信処理（Cron）もデプロイと同時に動き始めています。追加設定は不要です。

---

## STEP 2. Resend & 送信ドメインの設定

### 2-1. 独自ドメインを用意する

**すでにドメインを持っている場合** → 2-2 へ。

**持っていない場合**（取得先の例）:
- **Cloudflare Registrar**（おすすめ: 原価販売で安い・管理が1箇所で済む）
  Cloudflare ダッシュボード → 「ドメイン登録」→「ドメインの登録」から検索・購入
- お名前.com / ムームードメイン / Google Domains 系などでもOK

> メール専用に新規取得する場合、`.com` `.jp` など一般的なものが到達率の面で無難です。

### 2-2. Resend アカウント作成

1. https://resend.com で無料アカウントを作成（GitHub/Googleログイン可）
2. ログイン後のダッシュボードに入る

### 2-3. Resend にドメインを追加

1. Resend ダッシュボード → **Domains** → **Add Domain**
2. 用意したドメイン（例: `example.com`）を入力
3. **DNSレコードのリスト**（MX・TXT/SPF・DKIM など数件）が表示される

### 2-4. DNSレコードを登録

表示されたレコードを、**ドメインを管理しているサービスのDNS設定**にそのまま追加します。

- **Cloudflareでドメイン管理している場合**: ダッシュボード → 対象ドメイン → **DNS** → **レコードを追加** で、Resend に表示された Type / Name / Value を1件ずつ追加（Proxy は OFF=DNS only にする）
- お名前.com 等の場合: 各サービスの「DNSレコード設定」画面で同様に追加

追加後、Resend の Domains 画面で **Verify** を押します。ステータスが **Verified** になれば成功（数分〜24時間かかることがあります。待っている間に他のステップを進めてOK）。

### 2-5. Resend APIキーを発行・登録

1. Resend ダッシュボード → **API Keys** → **Create API Key**（権限は Sending access でOK）
2. 表示されたキー（`re_` で始まる文字列）をコピー（**この画面でしか表示されません**）
3. ターミナルで登録:

```bash
npx wrangler secret put RESEND_API_KEY
```

> ⚠️ APIキーはメモ帳やチャットに貼り残さないでください。この `secret put` で登録すれば手元に残す必要はありません（紛失時は再発行すればOK）。

### 2-6. 送信元アドレスと送信者表示を設定

`wrangler.jsonc` の2箇所を書き換えます:

```jsonc
"MAIL_FROM": "noreply@your-verified-domain.example",
      ↓ 検証済みドメインのアドレスに（@より前は自由。mail@ や info@ など）
"MAIL_FROM": "mail@あなたのドメイン.com",

"SENDER_INFO": "あなたの名称 / 住所 / 連絡先",
      ↓ あなたの正式な情報に
"SENDER_INFO": "○○○○（屋号または氏名） 東京都○○区…（住所） contact@….com",
```

> ⚖️ **SENDER_INFO は法律上の必須項目です**（特定電子メール法）。広告宣伝メールには送信者の氏名/名称と住所の表示、および配信停止手段の提供が義務付けられています。配信停止リンクはシステムが全メールに自動で付けるので、ここには正しい名称・住所を入れてください。

書き換えたら再デプロイ:

```bash
npm run deploy
```

---

## STEP 3. テスト配信 → 本番切替

### 3-1. テストモードのまま流れを確認

1. 管理画面 → 「購読者」で**自分のメールアドレス**を登録
2. 「リスト」を作成し、自分を追加
3. 「一斉配信」で配信を作成 → 予約 → **承認**
4. 「▶ スケジューラ実行」を押す → 配信が「送信済み」になる（DRY_RUNなので実際には届かない。ここまでの操作感を確認）

### 3-2. 実送信に切り替え

`wrangler.jsonc` を書き換え:

```jsonc
"DRY_RUN": "true",
      ↓
"DRY_RUN": "false",
```

```bash
npm run deploy
```

### 3-3. 自分宛てに1通、実送信テスト

3-1 と同じ手順で、**自分だけが入ったリスト**に配信します。

- ✅ 届いた → セットアップ完了！🎉 本文の下部に配信停止リンクと送信者表示が自動で付いていることも確認してください
- 📭 届かない → 迷惑メールフォルダを確認 → それでもなければ本ガイド末尾のトラブルシューティングへ

> 🛡 本番運用でも安全装置が常時働いています: 1回の処理で最大100通・1日最大2,000通（変更可）、承認していない配信は送信されない、配信停止・バウンス済みの人には送らない。

---

## STEP 4. 日常の使い方

- **使い方マニュアル**: `https://あなたのURL/manual/mail-studio/` に画像付きマニュアルが入っています（管理画面サイドバーからも開けます）
- **一斉配信**: 下書き → 予約 → 承認、の3段階。承認するまで絶対に送信されません
- **ステップメール**: シナリオを作り「連携リンク」と紐付けると、登録した人に自動で順次配信されます
- **外部連携**: 「連携リンク」で発行されるURLに、外部のフォームやツールから登録を流し込めます（Webhook / 埋め込みフォーム両対応）
- **ポイント & 抽選**: 開封・クリックで読者に自動でポイントが貯まり、読者マイページ（メール下部に自動リンク）でくじ引き・景品交換ができます

---

## トラブルシューティング FAQ

**Q. `npx wrangler login` でブラウザが開かない / 認証に失敗する**
A. ターミナルに表示されるURLを手動でブラウザに貼り付けてください。社内ネットワーク等でダメな場合は `npx wrangler login --browser=false` も試せます。

**Q. デプロイで database_id 関連のエラーが出る**
A. `wrangler.jsonc` の `database_id` が `REPLACE_WITH_...` のままになっていないか確認してください（STEP 1-4）。

**Q. 管理画面にログインできない**
A. ADMIN_PASSWORD の打ち間違いがないか確認。忘れた場合は `npx wrangler secret put ADMIN_PASSWORD` で新しいパスワードに再設定できます（再設定後に再デプロイ不要）。

**Q. メールが届かない**
A. 次の順で確認してください:
  1. 画面左下のバッジが **LIVE** になっているか（DRY_RUN のままだと送信されません）
  2. 配信が「承認済み」になっているか
  3. Resend の Domains が **Verified** になっているか
  4. 迷惑メールフォルダに入っていないか
  5. Resend ダッシュボードの **Logs** にエラーが出ていないか

**Q. 「送信済み」になるのが遅い**
A. 自動処理は毎分実行で、1回あたり最大100通（既定）です。大きなリストは数分〜に分けて送信されます。すぐ処理したい時は「▶ スケジューラ実行」を押してください。

**Q. 1日の上限を変えたい**
A. `wrangler.jsonc` の `MAX_SENDS_PER_DAY`（既定2000）と `MAX_SENDS_PER_TICK`（既定100）を変更して再デプロイ。Resend の契約プランの上限も併せて確認してください（無料枠は100通/日）。

**Q. エラーの意味が分からない / この FAQ にない問題が起きた**
A. Claude Code にエラーメッセージをそのまま貼り付けて聞いてください。このフォルダの構成を理解した上で対処法を教えてくれます。

---

## 💬 Claude Code への質問例（コピペで使えます）

- 「セットアップガイド.md に従って、セットアップを最初から手伝ってください」
- 「STEP 2 まで終わっています。続きをお願いします」
- 「このエラーが出ました: （エラーメッセージ貼り付け）」
- 「今どこまでセットアップが終わっているか確認してください」
- 「ステップメールのシナリオを一緒に作ってください」
- 「配信がちゃんと送られたか確認する方法を教えてください」
