マーケティングオートメーションサービス機能仕様書

項目	内容
文書名	マーケティングオートメーションサービス機能仕様書
バージョン	1.2
作成日	2026-08-13
想定利用形態	自社利用ツール(社内営業支援)
ステータス	レビュー待ち

1. はじめに

1.1 目的

本書は、自社の新規開拓営業を効率化するマーケティングオートメーション(以下「本システム」)の機能仕様を定義する。本システムは、企業リストの収集・管理からメール/問い合わせフォームによるアプローチ実行、効果分析までを一元的に支援する。

1.2 スコープ

本書が対象とする範囲は以下のとおり。

企業情報の自動リストアップ(都道府県 × 業種による収集)と連絡先の自動抽出
CSVによる企業情報のインポート
企業検索およびアプローチステータス管理
メールテンプレート/フォームテンプレートの管理
メール送信(SendGrid API連携)およびフォーム営業支援
メール/フォーム本文内URLへの計測パラメータ(ADコード)自動付与と、Google Analytics連携によるクリック反応の分析
アクセス数・返答率・クリック反応率の期間別分析
SendGrid APIキー等を管理する環境設定機能

以下は本書のスコープ外とする。

商談管理・受注管理などSFA/CRM領域の機能

1.3 用語定義

用語	定義
企業(Company)	アプローチ対象となる法人。本システムの管理単位
アプローチ(Approach)	1企業に対する1回の営業接触(メール送信またはフォーム送信)
キャンペーン	同一テンプレート・同一条件で複数企業にまとめてアプローチする単位
リストアップ	都道府県・業種を条件にインターネットから企業情報を収集する処理
連絡先抽出	企業サイトからサイトURL・問い合わせフォームURL・メールアドレスを抽出する処理
返答	アプローチに対する相手企業からの返信(メール返信・フォーム経由の連絡等)
ADコード	本文内URLに自動付与する計測パラメータ一式(UTMパラメータ+アプローチ単位の追跡コード)
クリック反応	アプローチ本文内のリンクがクリックされたこと。返答に準ずる「反応」として分析対象とする
SendGrid	メール送信基盤として利用する外部サービス。本システムからメール送信API(v3)を呼び出す
GA4	Google Analytics 4。自社サイトへのアクセスログ収集・取得に利用する

2. システム概要

図1 全体業務フロー(機能の連携イメージ)

2.1 システム構成(想定)

図2 システム構成図(想定)

2.2 技術スタック(想定)

レイヤ	想定技術	備考
フロントエンド	React または Vue(SPA)	画面仕様は特定FWに依存しない
バックエンド	Node.js(NestJS)/ Python(FastAPI)等	REST API
DB	SQLite(WALモード)	単一ファイルDB。書き込みはアプリケーション経由で直列化。全文検索はFTS5を利用。将来のRDBMS移行に備えORM経由でアクセスする
非同期処理	ジョブキュー(BullMQ / Celery 等)	収集・抽出・フォーム送信・GA同期は非同期実行
クローラ	ヘッドレスブラウザ(Playwright 等)	フォーム検出・フォーム送信に使用
メール送信	SendGrid API(v3)	本システムはSMTPを直接持たない
アクセス解析	Google Analytics 4(Data API)	自社サイトのアクセスログを定期取得

2.3 想定ユーザーと権限

自社利用のため権限は最小構成とする。

ロール	権限
管理者(admin)	全機能。ユーザー管理、環境設定(SendGrid APIキー・GA連携設定等)、データ削除
一般(member)	企業管理・アプローチ実行・テンプレート管理・分析閲覧

3. 機能要件

機能一覧を以下に示す。詳細は各節を参照。

機能ID	機能名	概要
F-01	企業リストアップ	都道府県・業種を条件にインターネットから企業情報を収集・保存
F-02	連絡先自動抽出	企業サイトからサイトURL・問い合わせフォームURL・メールアドレスを抽出・保存
F-03	企業情報CSVインポート	CSVファイルから企業情報を一括登録
F-04	企業検索・アプローチ管理	企業の検索、アプローチ履歴・ステータス管理、メール/フォーム営業の実行
F-05	メールテンプレート管理	メール営業用テンプレートの複数保存・管理
F-06	フォームテンプレート管理	フォーム営業用テンプレートの複数保存・管理
F-07	分析	月別・四半期別・半期別・年間のアクセス数・返答率・クリック反応率の集計・可視化
F-08	メール送信(SendGrid API連携)	SendGridメール送信APIの呼び出しによるメール送信と送達イベント管理
F-09	Google Analytics連携	本文内URLへのADコード自動付与と、GA4アクセスログの収集・クリック反応分析
F-10	環境設定	SendGrid APIキー・GA連携情報等の登録・検証・管理

3.1 F-01 企業リストアップ

3.1.1 概要

ユーザーが都道府県と業種を指定すると、インターネット上の公開情報から該当する企業をリストアップし、企業マスタに保存する。

3.1.2 入力

項目	必須	内容
都道府県	○	47都道府県から1つ以上選択(複数選択可)
業種	○	業種マスタから1つ以上選択(複数選択可)。日本標準産業分類(大分類・中分類)をベースとする
最大取得件数	-	1回の収集ジョブの上限件数(デフォルト100件、最大1,000件)
キーワード	-	任意の絞り込みキーワード(例:「製造金属加工」)

3.1.3 処理仕様

図3 企業リストアップ(F-01)処理フロー

ユーザーが条件を指定して「リストアップ開始」を実行すると、収集ジョブを非同期で起動する。
ワーカーは検索エンジンAPI・公開企業データベース等の企業情報ソースを検索し、条件に合致する企業の候補を収集する。
収集した各候補について、以下を取得する:企業名、住所(都道府県)、業種、サイトURL(判明した場合)、電話番号(判明した場合)。
既存データとの重複判定を行う(判定キー:企業名の正規化文字列+都道府県。サイトURLのドメイン一致も重複とみなす)。
重複しない企業を企業マスタに 収集元=auto として保存する。
保存完了後、各企業に対して連絡先抽出ジョブ(F-02)を自動起動する。
ジョブの進捗(待機中/実行中/完了/失敗、収集件数、重複スキップ件数)を画面で確認できる。

3.1.4 制約・例外

収集ジョブは同時実行数を制限する(デフォルト: 同時2ジョブ)。
情報ソースへのアクセスはレート制限を遵守し、リクエスト間隔を設ける。
収集元サイトの利用規約・robots.txt を尊重する(9章参照)。
収集結果が0件の場合もジョブは正常終了とし、その旨を表示する。

3.2 F-02 連絡先自動抽出

3.2.1 概要

企業のサイトURLを起点にクロールし、問い合わせフォームURLとメールアドレスを自動抽出して企業情報に保存する。

3.2.2 起動契機

F-01 のリストアップ完了後に自動起動
F-03 のCSVインポート時(オプション「連絡先を自動抽出する」ON時)
企業詳細画面からの手動起動(再抽出)

3.2.3 処理仕様

図4 連絡先自動抽出(F-02)処理フロー

サイトURL未設定の企業は、企業名+都道府県でWeb検索し公式サイトを推定する。推定確度が低い場合は「サイトURL要確認」フラグを立てる。
サイトのトップページおよび主要ページ(最大20ページ、深さ2階層まで)をクロールする。
問い合わせフォームURLの抽出:
リンクテキスト・URLパスのパターンマッチ(「お問い合わせ」「お問合せ」「contact」「inquiry」「form」等)
ページ内に <form> 要素と入力フィールド(氏名・メール・本文相当)が存在することを確認したURLを採用
メールアドレスの抽出:
ページ本文・mailto: リンクからメールアドレス形式の文字列を抽出
複数検出時は優先順位(info@ > contact@ > sales@ > その他)で代表アドレスを決定し、全件を候補として保存
抽出結果を企業情報に保存し、抽出ステータス(未抽出/抽出済/抽出失敗/フォーム無し・メール無し)を更新する。

3.2.4 出力項目

項目	内容
サイトURL	公式サイトのトップURL
問い合わせフォームURL	検出したフォームページのURL(複数候補時は代表1件+候補リスト)
メールアドレス	代表メールアドレス+検出された全候補
抽出日時	最終抽出実行日時
抽出ステータス	未抽出/抽出済/抽出失敗/フォーム無し/メール無し

3.3 F-03 企業情報CSVインポート

3.3.1 概要

CSVファイルをアップロードして企業情報を一括登録する。

3.3.2 CSVフォーマット

文字コードはUTF-8(BOM付き可)およびShift_JISに対応する。1行目はヘッダ行とする。

列名	必須	内容
企業名	○	法人名
都道府県	○	47都道府県名(表記ゆれは正規化:「東京」→「東京都」等)
業種	-	業種マスタ名称と突合。未一致時は「その他」+元の値をメモに保持
サイトURL	-	http(s)形式
問い合わせフォームURL	-	http(s)形式
メールアドレス	-	RFC準拠形式チェック
電話番号	-	任意形式
住所	-	任意テキスト
メモ	-	任意テキスト

3.3.3 処理仕様

図5 企業情報CSVインポート(F-03)処理フロー

アップロード後、まずバリデーション結果のプレビューを表示する(正常行数/エラー行数/重複行数)。
エラー行(必須欠落・形式不正)は行番号と理由を一覧表示し、エラー行のみのCSVをダウンロードできる。
重複判定はF-01と同一ロジック。重複時の動作は「スキップ/上書き(空欄項目のみ補完)」をインポート時に選択できる。
ユーザーが「インポート実行」を確定した時点で正常行を 収集元=csv として保存する。
オプション「連絡先を自動抽出する」ON時は、サイトURL・フォームURL・メールのいずれかが欠けている行に対しF-02を起動する。
1ファイルの上限は10,000行・10MBとする。

3.4 F-04 企業検索・アプローチ管理

3.4.1 概要

保存済みの企業を検索し、過去のアプローチ有無・状況を確認したうえで、メール営業またはフォーム営業を実行する。

3.4.2 検索条件

条件	内容
キーワード	企業名・メモの部分一致
都道府県	複数選択
業種	複数選択
アプローチステータス	複数選択(下記ステータス定義参照)
連絡先の有無	メールあり/フォームあり/両方なし
収集元	auto / csv / manual
最終アプローチ日	期間指定(例: 90日以上アプローチなし)

検索結果は一覧表示(ページング、既定50件/頁)し、並び替え(企業名/最終アプローチ日/登録日)に対応する。検索結果はCSVエクスポートできる。

3.4.3 アプローチステータス定義

図6 アプローチステータス遷移図(F-04)

企業ごとに以下のステータスを保持する。ステータスはアプローチ実行・返答登録により自動更新され、手動変更も可能とする。

ステータス	コード	内容	遷移契機
未アプローチ	not_approached	一度もアプローチしていない	初期値
アプローチ済(返答待ち)	approached	メールまたはフォームを送信済み	アプローチ実行(自動)
返答あり	replied	相手から返答があった	返答登録(手動/自動)
商談中	negotiating	やり取りが進行中	手動
成約	won	成約に至った	手動
見送り	lost	断られた・見込みなし	手動
アプローチ不可	do_not_contact	配信停止依頼・連絡先無効等。以後の送信対象から除外	手動/バウンス・配信停止(自動)

do_not_contact の企業は、メール・フォームいずれの一括送信対象からも自動的に除外する。
ステータス変更はすべて履歴(変更前後・変更者・日時)を記録する。
リンククリック(クリック反応)を検知した場合の扱いは F-09 参照(既定ではステータスは変更しない)。

3.4.4 アプローチ実行

図7 アプローチ実行(キャンペーン)フロー(F-04)

一覧から企業を複数選択(または検索条件全件)し、「メール営業」または「フォーム営業」を開始できる。
実行単位を「キャンペーン」として保存する(名称・テンプレート・対象企業・実行日時)。

メール営業:

メールテンプレート(F-05)を選択する。
差し込み変数を展開したプレビューを対象企業ごとに確認できる。
送信対象からの自動除外: メールアドレス未登録/do_not_contact/同一テンプレートで送信済(オプション)。
本文内URLにADコードを自動付与し(F-09)、SendGridメール送信API(F-08)を呼び出して、結果(受付成功/失敗)をアプローチ履歴に記録する。
企業ステータスを approached に更新する。

フォーム営業:

フォームテンプレート(F-06)を選択する。
実行モードは2種類とする:
半自動モード(既定): システムがフォームページを開き、テンプレート内容を各項目へ自動入力した状態でユーザーに提示。ユーザーが内容と送信可否を確認して送信する。
自動モード: ワーカーがフォーム項目を自動マッピングして送信まで実行する。CAPTCHA検出時・項目マッピング失敗時は自動送信を中止し「手動対応待ち」として一覧化する。
本文内URLにはメール営業と同様にADコードを自動付与する(F-09)。
送信結果(送信済/送信失敗/CAPTCHAによりスキップ/手動対応待ち)をアプローチ履歴に記録し、ステータスを更新する。

3.4.5 アプローチ履歴・返答管理

企業詳細画面にアプローチ履歴(日時・手段・テンプレート・キャンペーン・結果・担当者)を時系列表示する。クリック反応・開封等の送達イベントも同じタイムラインに表示する。
返答があった場合、ユーザーが「返答あり」を登録する(返答日・手段・内容メモ)。返答登録時にステータスを replied へ自動更新する。
SendGridの送達・開封・クリック等のイベントはEvent Webhookで自動反映する(7章参照)。

3.5 F-05 メールテンプレート管理

3.5.1 概要

メール営業に使用するテンプレートを複数保存・管理する。

3.5.2 項目

項目	必須	内容
テンプレート名	○	管理用名称(一意)
件名	○	差し込み変数使用可
本文	○	テキスト形式(HTMLメールは将来拡張)。差し込み変数使用可
差出人名	-	未指定時は環境設定(F-10)の既定値
返信先アドレス	-	未指定時は環境設定(F-10)の既定値
ステータス	○	下書き/有効/アーカイブ

3.5.3 差し込み変数

本文・件名内で以下の変数を使用できる。送信時に企業情報で展開する。

変数	展開内容
`{{company_name}}`	企業名
`{{prefecture}}`	都道府県
`{{industry}}`	業種
`{{sender_name}}`	差出人担当者名
`{{sender_company}}`	自社名

展開後に未解決の変数が残る場合は送信前チェックでエラーとする。
本文内のURLは、送信時にADコード(F-09)が自動付与される。プレビュー画面で付与後のURLを確認できる。
テンプレートは複製して新規作成できる。
更新時は版数を上げ、過去版を参照できる(アプローチ履歴には送信時点の版を紐付ける)。
特定電子メール法対応のため、本文フッターに自社の表示義務事項(社名・住所・連絡先)と配信停止の案内を挿入する共通フッター設定を持つ(9章参照)。

3.6 F-06 フォームテンプレート管理

3.6.1 概要

フォーム営業に使用するテンプレートを複数保存・管理する。フォームの標準的な入力項目に対応する値のセットとして定義する。

3.6.2 項目

項目	必須	内容
テンプレート名	○	管理用名称(一意)
会社名	○	自社名
担当者名(姓・名)	○	送信者の氏名
ふりがな(せい・めい)	-	かな・カナ両対応
メールアドレス	○	返信受取用アドレス
電話番号	○	ハイフンあり/なし両形式を保持
郵便番号・住所	-	フォームに項目がある場合に使用
部署・役職	-	同上
件名	-	問い合わせ件名欄がある場合に使用
本文	○	営業メッセージ。差し込み変数使用可(F-05と同一変数)。本文内URLはADコード自動付与の対象(F-09)
ステータス	○	下書き/有効/アーカイブ

3.6.3 フォーム項目自動マッピング

自動モード(F-04)では、フォームの各入力欄をラベル・name属性・placeholder等から解析し、テンプレート項目へマッピングする。

マッピング規則の例: 「会社名/貴社名/御社名」→会社名、「お名前/氏名/担当者」→担当者名、「メール/e-mail」→メールアドレス、「お問い合わせ内容/本文/メッセージ」→本文
必須項目にマッピングできない欄が残る場合は自動送信せず「手動対応待ち」とする。
「個人情報の取り扱いに同意する」等の同意チェックボックスは自動チェックするか否かを設定で選択できる(既定: 半自動モードでのみチェックし、ユーザー確認を経て送信)。

3.7 F-07 分析

3.7.1 概要

アプローチ活動の成果を期間別に集計・可視化する。

3.7.2 集計期間

月別(過去24か月)
四半期別(過去8四半期)
半期別(過去6半期)
年間(過去5年)

四半期・半期・年度の起点(1月始まり/4月始まり)は環境設定で選択できる(既定: 4月始まり)。

3.7.3 指標定義

指標	定義
アプローチ数	期間内に実行したアプローチ件数(メール受付成功+フォーム送信成功)。手段別内訳を表示
アクセス数	アプローチ起点の自社サイト等へのアクセス数。計測リダイレクト(F-09)による即時計測値(速報)と、GA4同期による確定値の2段構成で表示する
クリック反応数	期間内に本文内リンクをクリックした企業数(アプローチ単位で重複排除)。計測リダイレクト・SendGridクリックイベント・GA4ログを統合して判定する(F-09)
クリック反応率	クリック反応数 ÷ アプローチ数(%)
返答数	期間内に「返答あり」となったアプローチ件数
返答率	返答数 ÷ アプローチ数(%)。返答はアプローチ実行日の属する期間に帰属させる
拡張返答率	(返答数+クリック反応数)÷ アプローチ数(%)。環境設定「クリックを返答に含める」ON時に返答率と併記表示する(F-09)
ステータス内訳	期間内アプローチ対象企業の現在ステータス構成比

3.7.4 画面仕様

図8 分析ダッシュボード画面イメージ(F-07)

折れ線/棒グラフによる期間推移表示(アプローチ数・アクセス数・返答率・クリック反応率)
手段別(メール/フォーム)、テンプレート別、業種別、都道府県別のクロス集計表
表示中の集計データはCSVエクスポートできる

3.8 F-08 メール送信(SendGrid API連携)

3.8.1 概要

メール送信は自前のSMTPを使用せず、SendGridのメール送信API(v3 Mail Send)を呼び出して行う。APIの詳細インターフェースは7章に定義する。

3.8.2 処理仕様

メール営業実行時、対象企業ごとにテンプレートの差し込み変数を展開し、本文内URLへADコードを付与(F-09)したうえで、メール送信APIへ1件ずつ登録する。
API呼び出し結果(X-Message-Id・受付成否)をアプローチ履歴に保存する。custom_args にキャンペーンID・アプローチID・追跡コードを設定し、後続イベントとの突合キーとする。
失敗時は指数バックオフで最大3回リトライする。レート超過(429)時は Retry-After に従う。リトライ後も失敗した場合は「送信失敗」として一覧化し、再実行できる。
SendGridのEvent Webhook(送達・開封・クリック・バウンス・スパム報告・配信停止)を受信し、アプローチ履歴と分析指標に反映する。
バウンス(恒久的エラー)が通知された企業のメールアドレスは「無効」フラグを立て、以後の送信対象から除外する。スパム報告・配信停止の通知を受けた企業はステータスを do_not_contact に更新する。
SendGridのAPIキー等の認証情報は環境設定(F-10)で管理する。

3.9 F-09 Google Analytics連携(リンク自動計測)

3.9.1 概要

メール本文・フォーム本文に含まれるURLに、送信時に計測パラメータ(ADコード)を自動付与する。リンクがクリックされると、本システムでアクセスを即時計上したうえで自社サイトへ誘導し、自社サイトに設置したGoogle Analytics(GA4)の計測タグでアクセスログに記録される。本システムはGA4からアクセスログを定期取得してアプローチ単位で突合し、「クリック反応」として分析(F-07)に反映する。

図9 リンク自動計測とGoogle Analytics連携(F-09)

3.9.2 ADコード自動付与

対象: 差し込み変数展開後のメール本文・フォーム本文に含まれる http(s) 形式のURL(送信直前に書き換え)。配信停止リンク等のシステム生成リンクは対象外。

付与するパラメータ(ADコード):

パラメータ	値	内容
utm_source	ma(既定・変更可)	流入元識別子
utm_medium	email / form	アプローチ手段
utm_campaign	cp_{キャンペーンID}	キャンペーン識別子
utm_content	{tracking_code}	アプローチ単位の一意な追跡コード(ADコードの本体)

書き換え方式:

計測リダイレクト経由(既定): 本文内URLを https://{本システム}/r/{tracking_code} に置換する。クリック時に本システムがアクセスを即時計上し、ADコードを付与した元URLへ302リダイレクトする。
直接付与: リダイレクトを経由せず、元URLにADコードのみを付与する方式も環境設定で選択できる(この場合、本システム側のアクセス計上はGA同期時に反映される)。
元URLに既に utm_* パラメータが含まれる場合は上書きしない(環境設定で上書きに変更可)。

書き換え例:

テンプレート本文内のURL:
  https://www.example.co.jp/service

送信時(計測リダイレクト経由・既定):
  https://ma.example.com/r/Ab3xK9pQ

クリック後のリダイレクト先(ADコード付与済み):
  https://www.example.co.jp/service
    ?utm_source=ma&utm_medium=email&utm_campaign=cp_123&utm_content=Ab3xK9pQ

3.9.3 GAアクセスログ収集

GA4 Data API(runReport)を定期実行し(既定: 1時間毎の増分取得+日次の確定同期)、自社サイトのアクセスログを取得する。
取得ディメンション: date、sessionSource、sessionMedium、sessionCampaignName(utm_campaign)、sessionManualAdContent(utm_content)。取得指標: sessions、engagedSessions、screenPageViews。
utm_content(=tracking_code)でアプローチと突合し、送達イベント(event_type=ga_access)として保存する。突合できないレコードはキャンペーン単位で集計値として保持する。
GA4の集計データは反映まで24〜48時間の遅延があり得るため、分析画面では計測リダイレクトによる即時計測(速報値)とGA同期による確定値を区別して表示する。
GA連携の認証にはGoogleサービスアカウントを使用する(環境設定 F-10 で登録)。

3.9.4 クリック反応の分析

計測リダイレクトのアクセス・SendGridクリックイベント・GA4ログの3系統を統合し、アプローチ単位で「クリック反応」を判定する(同一アプローチの複数クリックは1反応として重複排除)。
分析指標として「クリック反応数」「クリック反応率」を集計する(F-07)。
環境設定「クリックを返答に含める」ON時は、返答数・返答率にクリック反応を加味した「拡張返答率」を併記表示する。
クリック検知時のステータスの扱い: 既定では企業ステータスは変更せず、企業詳細のアプローチ履歴タイムラインにクリックイベントを表示する。環境設定により「クリック検知時に replied(返答あり)へ自動更新」を選択できる(既定OFF)。

3.10 F-10 環境設定

3.10.1 概要

外部サービスの認証情報・送信既定値・システム全体の動作設定を管理する。設定画面(S-12)から管理者(admin)のみが操作できる。

3.10.2 設定項目

SendGrid設定:

項目	内容
APIキー	SendGridのAPIキー(Mail Send権限)。暗号化保存し、画面上はマスク表示(末尾4文字のみ)
接続テスト	APIキーの有効性検証(API疎通)と、指定アドレスへのテスト送信
差出人既定値	差出人メールアドレス・差出人名・返信先アドレスの既定値
送信ドメイン認証	Domain Authentication(SPF/DKIM)の設定状態を表示し、未設定時は警告する
Event Webhook	Webhook受信URL(本システムのエンドポイント)の表示と、署名検証用公開鍵の登録
送信レート	1分あたり最大送信数・1日あたり送信上限

Google Analytics設定:

項目	内容
GA4プロパティID	連携対象のGA4プロパティ
サービスアカウント	サービスアカウントキー(JSON)のアップロード。暗号化保存
接続テスト	Data APIの疎通確認
同期間隔	増分同期の間隔(既定1時間)・日次確定同期の実行時刻
ADコード既定値	utm_source の値(既定: ma)、リダイレクト経由/直接付与の選択、既存utm上書き可否
クリックの扱い	「クリックを返答に含める」「クリック検知時にステータス自動更新」のON/OFF(既定: 両方OFF)

共通設定:

項目	内容
共通フッター	メール本文末尾に自動挿入する署名・表示義務事項・配信停止案内(9章参照)
年度起点	分析の四半期・半期・年度の起点月(1月/4月、既定4月)
ユーザー管理	ユーザーの追加・無効化・ロール変更

3.10.3 処理仕様

APIキー・サービスアカウントキー等の秘匿情報は暗号化して保存し、登録後は平文を再表示しない。
設定の登録・変更・削除はすべて監査ログに記録する(値そのものは記録しない)。
SendGrid APIキー未設定の状態ではメール営業を実行できない(実行画面で設定を案内)。GA未設定の場合、クリック反応はリダイレクト計測とSendGridイベントのみで集計する(GA由来の確定値は表示しない)。
接続テストの結果(成功/失敗・日時)を設定画面に表示する。

4. 画面仕様

4.1 画面一覧

画面ID	画面名	概要	関連機能
S-01	ログイン	ID/パスワード認証	共通
S-02	ダッシュボード	直近のアプローチ数・返答率・クリック反応・実行中ジョブのサマリ	F-07
S-03	企業リストアップ	都道府県・業種指定と収集ジョブの起動・進捗確認	F-01
S-04	企業一覧・検索	検索条件・結果一覧・一括アプローチ起点	F-04
S-05	企業詳細	企業情報・連絡先・アプローチ履歴・ステータス変更	F-02/F-04
S-06	CSVインポート	ファイルアップロード・プレビュー・実行	F-03
S-07	メールテンプレート一覧/編集	テンプレートのCRUD・プレビュー	F-05
S-08	フォームテンプレート一覧/編集	テンプレートのCRUD	F-06
S-09	キャンペーン実行(メール)	テンプレート選択・対象確認・プレビュー・実行	F-04/F-08
S-10	キャンペーン実行(フォーム)	テンプレート選択・半自動/自動選択・進捗と手動対応待ち一覧	F-04/F-06
S-11	分析	期間別グラフ・クロス集計・CSVエクスポート	F-07
S-12	環境設定	SendGrid設定・GA連携設定・共通フッター・年度起点・ユーザー管理	F-10

図10 画面構成・遷移図

4.2 主要画面の補足

S-04 企業一覧・検索

左ペインに検索条件、右ペインに結果一覧を表示する。
一覧列: チェックボックス/企業名/都道府県/業種/メール有無/フォーム有無/ステータス/最終アプローチ日。
ステータスは色付きバッジで表示する(未アプローチ=グレー、返答待ち=青、返答あり=緑、商談中=紫、成約=金、見送り=薄赤、アプローチ不可=赤)。
選択件数と「メール営業」「フォーム営業」ボタンを画面下部に固定表示する。

S-05 企業詳細

基本情報・連絡先(抽出ステータス・再抽出ボタン付き)・アプローチ履歴タイムライン・メモを1画面に表示する。
タイムラインには送信・開封・クリック(計測リダイレクト/SendGrid/GA)・返答・ステータス変更を時系列で表示する。
「返答あり登録」ボタンから返答日・手段・メモを入力できる。

S-09/S-10 キャンペーン実行

ステップ形式(対象確認 → テンプレート選択 → プレビュー → 実行確認)とし、実行前に送信対象件数・除外件数(除外理由別)を必ず表示する。
プレビューでは差し込み展開後の本文と、ADコード付与後のURLを確認できる。

S-12 環境設定

「SendGrid」「Google Analytics」「共通」のタブ構成とする。
SendGrid APIキー・GAサービスアカウントは登録済み/未登録の状態と接続テスト結果を表示する。

5. データベース設計

DBはSQLite(WALモード)を使用する。日時はISO 8601形式のTEXT(UTC)、JSONはTEXTに格納する。外部キー制約は PRAGMA foreign_keys=ON で有効化する。

5.1 ER概要

図11 ER図(主要テーブルの関連)

5.2 テーブル定義(主要)

companies(企業)

カラム	型	制約	内容
id	INTEGER	PK AUTOINCREMENT	企業ID
name	TEXT	NOT NULL	企業名
name_normalized	TEXT	NOT NULL, INDEX	重複判定用正規化名
prefecture_code	TEXT	NOT NULL, INDEX	JIS X 0401 都道府県コード(2桁)
industry_id	INTEGER	FK(industries)	業種
site_url	TEXT		サイトURL
site_url_verified	INTEGER	DEFAULT 0	サイトURL確認済フラグ(0/1)
contact_form_url	TEXT		問い合わせフォームURL
email	TEXT		代表メールアドレス
email_invalid	INTEGER	DEFAULT 0	バウンス等による無効フラグ(0/1)
phone	TEXT		電話番号
address	TEXT		住所
source	TEXT	NOT NULL	auto / csv / manual
extraction_status	TEXT	DEFAULT 'pending'	pending / done / failed / no_form / no_email
approach_status	TEXT	NOT NULL DEFAULT 'not_approached', INDEX	3.4.3のステータスコード
last_approached_at	TEXT	INDEX	最終アプローチ日時(ISO 8601)
memo	TEXT		メモ
created_at / updated_at	TEXT	NOT NULL	作成・更新日時

UNIQUE制約: (name_normalized, prefecture_code)
サイトURLのドメイン部は生成列(GENERATED COLUMN)+INDEXで重複判定に使用
企業名・メモの部分一致検索にはFTS5仮想テーブル(companies_fts)を併用

company_contacts(抽出連絡先候補)

カラム	型	内容
id	INTEGER PK
company_id	INTEGER FK(companies)
kind	TEXT	email / form_url
value	TEXT	抽出値
is_primary	INTEGER	代表フラグ(0/1)
extracted_at	TEXT	抽出日時

industries(業種マスタ)

カラム	型	内容
id	INTEGER PK
parent_id	INTEGER	大分類への自己参照(中分類の場合)
code	TEXT	産業分類コード
name	TEXT	業種名

mail_templates / mail_template_versions

テーブル	主要カラム
mail_templates	id, name(UNIQUE), status(draft/active/archived), current_version_no, created_by, created_at, updated_at
mail_template_versions	id, template_id FK, version_no, subject, body, from_name, reply_to, created_at

form_templates / form_template_versions

テーブル	主要カラム
form_templates	id, name(UNIQUE), status, current_version_no, created_by, created_at, updated_at
form_template_versions	id, template_id FK, version_no, company_name, person_last_name, person_first_name, kana_last, kana_first, email, phone, postal_code, address, department, title, subject, body, created_at

campaigns(キャンペーン)

カラム	型	内容
id	INTEGER PK
name	TEXT	キャンペーン名
channel	TEXT	mail / form
template_version_id	INTEGER	使用テンプレート版(mail/formいずれかのversion)
form_mode	TEXT	semi_auto / auto(formのみ)
status	TEXT	draft / running / done / canceled
created_by	INTEGER FK(users)	実行者
executed_at	TEXT	実行日時

approaches(アプローチ)

カラム	型	内容
id	INTEGER PK
company_id	INTEGER FK(companies), INDEX	対象企業
campaign_id	INTEGER FK(campaigns), INDEX	所属キャンペーン(単発時はNULL可)
channel	TEXT	mail / form
result	TEXT	accepted / sent / failed / skipped_captcha / manual_pending
sendgrid_message_id	TEXT	SendGridの X-Message-Id(メール時)
tracking_code	TEXT UNIQUE	ADコード・アクセス計測用の一意コード
clicked	INTEGER DEFAULT 0	クリック反応フラグ(0/1。重複排除済み)
first_clicked_at	TEXT	初回クリック日時
replied_at	TEXT	返答日時
reply_channel	TEXT	返答手段(mail/form/phone/other)
reply_memo	TEXT	返答内容メモ
approached_at	TEXT, INDEX	アプローチ日時
created_by	INTEGER FK(users)	実行者

approach_events(送達イベント)

カラム	型	内容
id	INTEGER PK
approach_id	INTEGER FK(approaches), INDEX
event_type	TEXT	delivered / opened / clicked / bounced / spam_report / unsubscribed / access / ga_access
source	TEXT	sendgrid / redirect / ga
occurred_at	TEXT	発生日時
payload	TEXT(JSON)	通知の生データ・GAディメンション等

ga_campaign_stats(GA集計・未突合分)

カラム	型	内容
id	INTEGER PK
date	TEXT	集計日
utm_campaign	TEXT	キャンペーン識別子
utm_content	TEXT	追跡コード(突合できなかったもの含む)
sessions / engaged_sessions / page_views	INTEGER	GA4指標
synced_at	TEXT	同期日時

UNIQUE制約: (date, utm_campaign, utm_content)。同期のたびにUPSERTする。

settings(環境設定)

カラム	型	内容
key	TEXT PK	設定キー(例: sendgrid.api_key, ga.property_id, footer.body, fiscal.start_month)
value	TEXT	設定値。秘匿情報は暗号化した値を格納
is_secret	INTEGER	秘匿フラグ(0/1)。1の場合は画面上マスク表示
updated_by	INTEGER FK(users)	最終更新者
updated_at	TEXT	最終更新日時

listing_jobs(リストアップジョブ)/ extraction_jobs(抽出ジョブ)/ import_jobs(インポートジョブ)

テーブル	主要カラム
listing_jobs	id, prefecture_codes(JSON), industry_ids(JSON), keyword, max_count, status(queued/running/done/failed), found_count, saved_count, dup_count, created_by, started_at, finished_at, error
extraction_jobs	id, company_id FK, trigger(auto/csv/manual), status, result_summary, started_at, finished_at, error
import_jobs	id, filename, total_rows, ok_rows, error_rows, dup_rows, dup_policy(skip/merge), auto_extract(0/1), status, created_by, created_at

status_histories(ステータス変更履歴)

カラム	型	内容
id	INTEGER PK
company_id	INTEGER FK(companies)
from_status / to_status	TEXT	変更前後
changed_by	INTEGER FK(users) NULL可	NULL=システム自動
reason	TEXT	approach_executed / reply_registered / manual / bounce / unsubscribe 等
changed_at	TEXT

users(ユーザー)

カラム	型	内容
id	INTEGER PK
email	TEXT UNIQUE	ログインID
name	TEXT	表示名
role	TEXT	admin / member
password_hash	TEXT	bcrypt等
is_active	INTEGER	0/1

5.3 SQLite利用上の設計方針

WALモードを有効化し、読み取りと書き込みの並行性を確保する(PRAGMA journal_mode=WAL)。
書き込みはアプリケーションサーバ/ワーカーのジョブキュー経由で直列化し、SQLITE_BUSY に備えて busy_timeout を設定する。
大量INSERT(リストアップ・CSVインポート・GA同期)はトランザクションでまとめて実行する。
集計高速化のため、分析用の日次集計テーブル(daily_stats)を日次バッチで生成する。
バックアップはオンラインバックアップAPI(VACUUM INTO / .backup)による日次スナップショットとする(8章参照)。

6. 内部API設計

REST APIとして設計する。認証はセッションまたはJWT。すべて /api/v1 配下。

6.1 エンドポイント一覧

メソッド	パス	機能
POST	/listing-jobs	リストアップジョブ起動(F-01)
GET	/listing-jobs, /listing-jobs/{id}	ジョブ一覧・進捗取得
POST	/companies/{id}/extract	連絡先再抽出(F-02)
POST	/import-jobs	CSVアップロード・検証(F-03)
POST	/import-jobs/{id}/execute	インポート確定実行
GET	/companies	企業検索(F-04。クエリで3.4.2の条件指定)
GET/PATCH	/companies/{id}	企業詳細取得・更新(ステータス変更含む)
POST	/companies/{id}/reply	返答あり登録
GET	/companies/export	検索結果CSVエクスポート
GET/POST	/mail-templates	メールテンプレート一覧・作成(F-05)
GET/PATCH/DELETE	/mail-templates/{id}	取得・更新(新版作成)・アーカイブ
GET/POST	/form-templates	フォームテンプレート一覧・作成(F-06)
GET/PATCH/DELETE	/form-templates/{id}	取得・更新・アーカイブ
POST	/campaigns	キャンペーン作成(対象企業+テンプレート指定)
POST	/campaigns/{id}/execute	キャンペーン実行(F-04/F-08)
GET	/campaigns/{id}	実行状況・結果取得
GET	/campaigns/{id}/manual-pending	フォーム手動対応待ち一覧
GET	/analytics/summary	分析サマリ(F-07。period=month/quarter/half/year)
GET	/analytics/export	分析CSVエクスポート
POST	/webhooks/sendgrid	SendGrid Event Webhook受信(7章)
POST	/integrations/ga/sync	GAデータ手動同期の起動(F-09)
GET	/r/{tracking_code}	計測用リダイレクト(アクセス計上→ADコード付与済みURLへ302)
GET/PUT	/settings	環境設定の取得・更新(F-10。管理者のみ)
POST	/settings/sendgrid/test	SendGrid接続テスト・テスト送信(F-10)
POST	/settings/ga/test	GA Data API疎通確認(F-10)

6.2 共通仕様

レスポンスはJSON。エラーは { "error": { "code", "message", "details" } } 形式。
一覧系は page / per_page(最大200)/ sort / order クエリに対応。
更新系は監査ログ(誰が・いつ・何を)を記録する。

7. 外部連携仕様

本章では SendGrid(メール送信)と Google Analytics 4(アクセスログ取得)の連携仕様を定義する。認証情報はいずれも環境設定(F-10)で管理する。

図12 SendGrid API連携シーケンス(F-08)

7.1 SendGrid メール送信API

エンドポイント: POST https://api.sendgrid.com/v3/mail/send

認証: Authorization: Bearer {API_KEY}

リクエスト例:

{
  "personalizations": [
    {
      "to": [{ "email": "info@example.co.jp" }],
      "custom_args": {
        "campaign_id": "123",
        "approach_id": "456",
        "tracking_code": "Ab3xK9pQ"
      }
    }
  ],
  "from": { "email": "sales@synon.co.jp", "name": "株式会社Synon 田中" },
  "reply_to": { "email": "mtanaka@synon.co.jp" },
  "subject": "【ご提案】◯◯業務の効率化について",
  "content": [
    { "type": "text/plain", "value": "株式会社◯◯ ご担当者様 …" }
  ]
}

レスポンス: 成功時 202 Accepted(ボディなし)。レスポンスヘッダ X-Message-Id を受付IDとして保存する。

ステータスコード	本システムの扱い
202 Accepted	result=accepted として履歴保存
400 バリデーションエラー	result=failed(リトライしない)。エラー内容を履歴に記録
401/403 認証エラー	ジョブ中断、管理者へ通知(APIキーの確認を案内)
413 ペイロード超過	result=failed(リトライしない)
429 レート超過	`Retry-After` に従い再試行
5xx	指数バックオフで最大3回リトライ

SendGridのクリックトラッキング(click_tracking)は無効とし、クリック計測は本システムのADコード方式(F-09)に統一する(二重リダイレクト・URL書き換えの競合を避けるため)。開封トラッキング(open_tracking)は有効とする。

7.2 SendGrid Event Webhook

SendGridのEvent Webhookを POST /api/v1/webhooks/sendgrid で受信する。Signed Event Webhook(公開鍵による署名検証)を必須とし、公開鍵は環境設定(F-10)で登録する。

受信イベント例:

[
  {
    "email": "info@example.co.jp",
    "event": "delivered",
    "timestamp": 1786800000,
    "sg_message_id": "dXNlcjEg...",
    "campaign_id": "123",
    "approach_id": "456",
    "tracking_code": "Ab3xK9pQ"
  }
]

custom_args に設定した値が各イベントにそのまま含まれるため、approach_id で該当アプローチを特定し、approach_events に保存する。

SendGridイベント	本システムの扱い
processed / delivered	event_type=delivered として保存
open	event_type=opened として保存
click	event_type=clicked として保存し、クリック反応判定(F-09)に反映
bounce(恒久)/ dropped	event_type=bounced。企業の email_invalid を1に更新
spamreport	企業ステータスを `do_not_contact` に更新
unsubscribe / group_unsubscribe	企業ステータスを `do_not_contact` に更新

Webhookはバッチ(配列)で届くため、イベント単位で冪等に処理する(sg_event_id による重複排除)。
Event Webhookが利用できない期間の欠損に備え、日次でバウンス一覧API(Suppressions)を照会し、email_invalid の整合を取る。

7.3 Google Analytics 4(Data API)連携

認証: Googleサービスアカウント(JSONキー)。対象GA4プロパティに閲覧者権限を付与する。

取得方法: GA4 Data API properties/{propertyId}:runReport を定期実行する(既定: 1時間毎の増分+日次確定同期)。