Benchmark Email APIとは？できること・料金・使い方をGoogleスプレッドシート連携の例つきで解説

メールマーケティングツールの「Benchmark Email」には、連絡先やキャンペーンの情報を外部のツールとやり取りできる公式APIが用意されています。EC・予約システム・CRM・Googleスプレッドシートなどで管理しているデータをBenchmark Emailと自動で同期できるので、「毎週CSVを書き出してインポートし直す」という作業から解放されます。

この記事では、Benchmark Email APIの概要、できること・できないこと、利用条件、APIキーの取得方法、そして Googleスプレッドシートと連携する具体例 までを、2026年10月時点の公式ドキュメントをもとに詳しく解説します。

Benchmark Email APIとは

Benchmark Email APIは、Benchmark Emailのアカウントを外部のソフトウェアと接続するための仕組みです。公式ページでは「スタックは相互に連携するべき」というコンセプトで紹介されており、次のような特徴があります。

• JSON over HTTP（一般的なREST形式）で、OpenAPI仕様も公開されている
• APIキーによる認証（X-API-Key ヘッダー）
• スコープ付きの権限で、連絡先・キャンペーン・レポート・ドメインごとにアクセス範囲を制限できる
• キーごとに有効期限を設定でき、削除せずに無効化・再有効化もできる
• 時間単位・月単位のレート制限があり、レスポンスヘッダーで残量を確認できる
• 主要なワークフロー向けのシナリオガイドや、Benchmark Classicからの移行ガイドがある

そして重要なのが、APIはすべてのプランで追加料金なしで使えるという点です。必要なのは、利用可能な状態のアカウントとAPIキーだけです。

誰向けのAPIなのか

公式ページでは、次のような悩みを解決する機能として紹介されています。

• ECサイトの顧客、スプレッドシートの見込み客、POSやCRMの連絡先がバラバラに存在している
• メールリストを作るために、CSVのエクスポート → クリーニング → インポートを繰り返している
• キャンペーンの結果を、毎回スプレッドシートやスライドにコピペしている

つまり、複数のツールにデータが散らばっていて、手作業で名寄せしているチーム向けです。逆に、Benchmark Emailの画面だけで完結している場合は、APIを使う必要はありません。

Benchmark Email APIでできること

APIで扱えるリソースは、大きく4つです。

連絡先の管理

もっとも使う機会が多いのが連絡先まわりです。

• 連絡先の作成・更新・削除：メールアドレスをキーに、名前や任意のカスタムフィールドを持った連絡先を登録できます。
• 検索とセグメント：メールアドレス、メールドメイン、カスタムフィールド、タグ、リスト、ステータス、作成日・更新日などで検索できます。条件は「等しい」「含む」「前方一致」「期間内」「空である」など複数の演算子から選べ、AND/ORの組み合わせも可能です。
• 重複チェック：作成前にメールアドレスで検索すれば、すでに登録済みの連絡先を二重に追加するのを防げます。
• 差分更新：リストへの追加・削除、タグの付け外し、フィールド更新を、1件の連絡先に対してまとめて行うエンドポイントもあります。
• エクスポートとイベント取得：連絡先のエクスポートや、連絡先ごとのイベント履歴も取得できます。

リストの管理

リストの作成・名前の変更・複製・結合・削除がAPI経由で可能です。CRMやECツール側が「顧客をどうグループ分けするか」の正解を持っている場合に便利です。たとえば「購入回数3回以上」「会員ランクがゴールド」といったグループを、外部システム側で判定してBenchmarkのリストに反映する、といった使い方ができます。

なお、結合は元のリストを残したまま新しいリストを作る形で、重複した連絡先は自動で処理されます。

キャンペーンの作成・設定

キャンペーン名、件名、プレビューテキスト、送信者名・送信元アドレス、返信先、受信者リスト、HTML本文などをAPIから設定し、下書きとして作成できます。既存キャンペーンの複製も可能で、複製したものは元の状態にかかわらず必ず下書きになります。

レポートの取得

次の5種類の情報を取得できます。

• ダッシュボードの概要（直近1〜90日。前期間との増減率つき）
• 全体の配信パフォーマンス（送信数・到達数・開封・クリック・バウンス・配信停止・苦情）
• 配信パフォーマンスの時系列データ（グラフ化に便利）
• 個別キャンペーンのレポート（リンクごとのクリック数を含む）
• 個別キャンペーンのエンゲージメントの推移

BIツールや自分用のダッシュボードにデータを流し込めば、「開封率をスライドにコピペする」作業をなくせます。

送信ドメインの確認

プライベート送信ドメインの認証ステータスを読み取ることができます。配信到達率の監視を別のダッシュボードで行いたい場合や、別システムに「このドメインから送れる状態になった」と知らせたい場合に使えます。

アカウント情報の取得

GET /api/account で、アカウントの都市・国・国コード・通貨コード・タイムゾーンといった基本情報を取得できます。ほかのエンドポイントを呼ぶ前に、APIキーが正しく動いているかの確認や、レポート取得時のタイムゾーンを合わせる用途で使えます。なお、レスポンスに含まれる unlayerKey はUnlayer連携用の秘匿キー（SHA256ハッシュ）なので、ログや画面に不用意に出さないようにしてください。

APIでできないこと（Benchmark Emailの画面に残るもの）

APIは万能ではなく、「安全な配信のために意図的に残されている操作」があります。

つまり、「誤送信が起きるような操作」はAPIキーからは実行できない設計になっています。キャンペーンの下書きまではAPIで準備し、最後の確認と送信ボタンは人間が押す、という運用が前提です。

利用条件・レート制限・料金

料金とAPIキーの数

• APIそのものは全プランで無料
• 無料プランはアクティブなAPIキー2つ、Proプランは最大10個まで（10個を超える場合は営業に相談）
• 公式は「連携ごとにキーを1つ作る」運用を推奨しています。スコープ（権限）をキーごとに絞れ、不要になったときに個別に無効化できるためです

レート制限と月間クォータ

開発者ドキュメントによると、制限は次のとおりです。

たとえば連絡先の上限が仮に1,000件のプランなら、無料プランで月1万リクエスト、有料プランで月10万リクエストが目安になります（あくまで計算例です。実際の数値は契約中のプランで確認してください）。

制限を超えると 429 Too Many Requests が返り、Retry-After ヘッダーで待機秒数が示されます。レスポンスには X-RateLimit-Remaining（時間あたりの残り）や X-Monthly-Remaining（月間の残り）といったヘッダーも付くため、残量を見ながら処理を調整できます。

また、無効なAPIキーでの試行を繰り返すと、そのIPアドレスが一時的にブロックされます。401 が続いたら、リトライを繰り返さずにキーを見直してください。

その他の条件

• APIキーを作成・管理できるのはオーナー権限のユーザーのみ
• アカウントが「有効（Open）」または「解約予定（Pending Cancel）」の間だけキーが使える（支払い遅延や停止中は 403）
• すべてのリクエストにUser-Agentヘッダーが必須（後述）

APIキーの取得から最初のリクエストまで

1. APIキーを作成する

1. オーナーアカウントでBenchmark Emailにログインする
2. Settings（設定）> API Keys を開く
3. Create API Key をクリックする
4. わかりやすい名前（例：Sheets Sync）を付け、必要なスコープだけを選ぶ
5. 必要なら有効期限を設定する（未設定なら無期限）
6. 作成後に表示されるキーをその場でコピーして安全に保管する

キーが表示されるのは作成時の1回だけです。紛失した場合は、API Keysの画面から再生成できますが、古いキーは無効になります。

APIキーは bme_ ＋ 2文字のリージョンコード（us、jp、eu など）＋ 43文字のランダムな文字列で、合計50文字です。

2. ベースURLを確認する

ベースURLはアカウントのリージョンとクラスターによって異なり、https://api-{region}-{cluster}.benchmarkemail.io という形式です（例：https://api-us-west-2-a.benchmarkemail.io）。Settings > API Keys の画面に自分のベースURLが表示されるので、それを使います。

3. 最初のリクエストを送る

curl -H "X-API-Key: bme_your-api-key-here" \
  -H "User-Agent: MyIntegration/1.0" \
  "<your-api-base-url>/api/contact-structure"

連絡先の構造（カスタムフィールドの定義）がJSONで返ってくれば成功です。401 や 403 が出る場合は、キー・スコープ・アカウントの状態を確認します。

403でJSONではなくHTMLが返ってくる場合は、User-Agent ヘッダーが送られていない可能性が高いです。Benchmark Emailのエッジ保護がUser-Agentのないリクエストを弾くためで、curlや主要言語の標準ライブラリは自動で付けてくれますが、PHPのcURL拡張などは明示的に設定する必要があります。

注意：マーケティング用の紹介ページに載っているcurlのサンプル（/v1/contacts に list_id を渡す形式）と、開発者ドキュメントのエンドポイント（/api/contact に contactStructureId とフィールドの _id を渡す形式）は書き方が異なります。実装するときは、必ず開発者ドキュメント（developers.benchmarkemail.io）のほうに従ってください。

スコープの考え方

APIキーには、{リソース}:{アクセス種別} 形式のスコープを付けます。

ポイントは次の3つです。

• writeはreadを含む：contacts:write があれば、連絡先の読み取りもできます
• 最小権限の原則：たとえば、レポートのダッシュボード用なら reports:read だけ、スプレッドシートから連絡先を同期するなら contacts:write だけ、という具合にキーを分けます
• 検索はreadで足りる：連絡先の検索はPOSTで行いますが、必要なのは contacts:read だけです

具体的な活用例

ここからは、公式ドキュメントの仕様をもとに、実際に使えそうな連携例を考えてみます。

注意：以下のコードは公式ドキュメントの仕様に沿って書いたサンプルです。本番のリストに対して実行する前に、必ずテスト用のリストや少数のデータで動作を確認してください。

例1：Googleスプレッドシート → Benchmark Emailに連絡先を同期する

セミナー申込やアンケートの回答を、Googleスプレッドシートに集めているケースを想定します。新しく追加された行だけをBenchmark Emailのリストに登録し、登録済みのメールアドレスは重複させないようにします。

事前準備

1. contacts:write スコープのAPIキーを作成する
2. GET /api/contact-structure で、連絡先構造の _id と、「姓」「名」フィールドの _id を控える
3. 登録先リストの _id を控える（GET /api/contact-structure/{構造ID}/lists/all で一覧を取得できる）
4. スプレッドシートの1行目をヘッダーにして、A列＝メール、B列＝姓、C列＝名、D列＝同期結果とする
5. Apps Scriptの「スクリプトプロパティ」に、APIキーやIDを保存する（コードに直書きしない）

Google Apps Scriptのコード

// ===== 設定（スクリプトプロパティに保存） =====
const P = PropertiesService.getScriptProperties();
const BASE_URL = P.getProperty('BME_BASE_URL');           // 例: https://api-us-west-2-a.benchmarkemail.io
const API_KEY = P.getProperty('BME_API_KEY');             // bme_jp_...
const STRUCTURE_ID = P.getProperty('BME_STRUCTURE_ID');   // 連絡先構造の _id
const LAST_NAME_ID = P.getProperty('BME_LAST_NAME_FIELD_ID');
const FIRST_NAME_ID = P.getProperty('BME_FIRST_NAME_FIELD_ID');
const LIST_ID = P.getProperty('BME_LIST_ID');

// ===== 共通のAPI呼び出し =====
function api_(method, path, body, retry) {
  retry = retry || 0;
  const res = UrlFetchApp.fetch(BASE_URL + path, {
    method: method,
    contentType: 'application/json',
    headers: { 'X-API-Key': API_KEY, 'User-Agent': 'SheetsToBenchmark/1.0' },
    payload: body ? JSON.stringify(body) : undefined,
    muteHttpExceptions: true,
  });
  const code = res.getResponseCode();
  if (code === 429 && retry < 3) {          // レート制限：待ってからリトライ
    Utilities.sleep(60 * 1000);
    return api_(method, path, body, retry + 1);
  }
  if (code >= 400) throw new Error(code + ' ' + res.getContentText());
  const text = res.getContentText();
  return text ? JSON.parse(text) : null;
}

// ===== メールアドレスの重複チェック =====
function emailExists_(email) {
  const r = api_('post', '/api/contact/search', {
    contactStructureId: STRUCTURE_ID,
    page: 1,
    pageSize: 1,
    source: ['_id'],
    contactSpecification: {
      filters: [{ criterias: [{ columnToFilter: 'KEY', operator: 'EQ', values: [email] }] }],
    },
  });
  return r.totalRecords > 0;
}

// ===== 未同期の行だけを登録 =====
function syncNewRows() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('申込者');
  const rows = sheet.getDataRange().getValues();

  for (let i = 1; i < rows.length; i++) {
    const email = String(rows[i][0]).trim();
    const lastName = rows[i][1];
    const firstName = rows[i][2];
    const synced = rows[i][3];
    if (!email || synced) continue;       // 空行・同期済みはスキップ

    let result;
    if (emailExists_(email)) {
      result = '登録済みのためスキップ';
    } else {
      api_('post', '/api/contact', {
        key: email,
        contactStructureId: STRUCTURE_ID,
        fields: [
          { _id: LAST_NAME_ID, value: lastName },
          { _id: FIRST_NAME_ID, value: firstName },
        ],
        lists: [{ _id: LIST_ID }],
      });
      result = '同期済み ' + new Date().toLocaleString('ja-JP');
    }
    sheet.getRange(i + 1, 4).setValue(result);
    Utilities.sleep(300);                  // 連続リクエストを避ける
  }
}

あとは、Apps Scriptの時間主導型トリガーで「1時間ごと」や「毎朝」に syncNewRows を実行すれば、スプレッドシートに行が増えるたびに自動でBenchmark Emailのリストへ反映されます。Googleフォームの回答先シートなら、「フォーム送信時」のトリガーにすることも可能です。

1行あたり最大2リクエスト（検索＋作成）なので、3,600リクエスト/時の上限には十分な余裕があります。

例2：配信結果をGoogleスプレッドシートに自動で書き出す

次は逆方向の例です。配信済みキャンペーンの成果を、スプレッドシートに自動で集計します。キャンペーン一覧のAPI（GET /api/email/campaign）は、配信済みキャンペーンの統計（開封数・クリック数・開封率など）も一緒に返してくれます。先ほどの api_ 関数をそのまま使い回せます。

campaigns:read スコープのキーがあれば動きます。

function exportCampaignStats() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName('配信レポート') || ss.insertSheet('配信レポート');

  const res = api_('get', '/api/email/campaign?page=1&size=25&statuses=sent&sort=scheduledAt:desc');

  const header = ['キャンペーン名', '件名', '配信日時', '配信数', '到達数',
                  '開封数(ユニーク)', '開封率(%)', 'クリック数(ユニーク)', 'クリック率(%)'];
  const rows = res.records.map(function (c) {
    const s = c.stats || {};
    return [
      c.name, c.subject, c.scheduledAt,
      s.sent, s.delivered,
      s.opens && s.opens.unique, s.opens && s.opens.rate,
      s.clicks && s.clicks.unique, s.clicks && s.clicks.rate,
    ];
  });

  sheet.clearContents();
  sheet.getRange(1, 1, 1, header.length).setValues([header]);
  if (rows.length) sheet.getRange(2, 1, rows.length, header.length).setValues(rows);
}

毎朝のトリガーで実行しておけば、シートを開くだけで最新の成果がそろいます。あとは、Googleスプレッドシートの標準機能でグラフを作ったり、Looker Studioに接続したりして、週次レポートを自動化できます。

さらに詳しい分析が必要なら、レポートAPIを併用します。

• GET /api/reports/dashboard?pastDays=30&timezone=Asia/Tokyo：直近30日の概要（前期間との増減率つき）
• GET /api/reports/email/{キャンペーンID}：特定のキャンペーンのリンク別クリック数
• GET /api/reports/email/{キャンペーンID}/engagement?period=week：配信後1週間の開封・クリックの推移

timezone に Asia/Tokyo を指定しておくと、日付の区切りが日本時間で集計されるので、日本向けのレポートでは便利です。

例3：ECサイトや予約フォームの顧客を自動でリストに追加する（n8n・Zapierなど）

Benchmark Emailには、現時点でノーコードのワークフローツールは内蔵されていません。ただし、公式ドキュメントでも「Zapierやn8nのようなツールでワークフローをAPI経由で自動化できる」と紹介されています。HTTPリクエストを送れるノード（n8nのHTTP Requestノード、ZapierのWebhooksなど） を使えば、コードをほとんど書かずに連携できます。

たとえば、こんな流れです。

1. トリガー：ECサイトで注文が入った／予約フォームが送信された／Googleフォームに回答があった
2. 検索：POST /api/contact/search で、メールアドレスが登録済みか確認する
3. 分岐
   • 未登録 → POST /api/contact で新規作成し、リストに追加する
   • 登録済み → 差分更新のエンドポイントで、リストの追加やタグの付与、フィールドの更新を行う
4. 通知：必要なら、SlackやChatworkに「新規登録しました」と知らせる

検索のときに FIELD_ID で絞り込めば、「会員ランクがゴールドの人だけ」といった条件の確認もできます。顧客データの正解をECツールやCRMに持たせたまま、Benchmark Email側のリストを自動で最新に保てます。

例4：先月のニュースレターを複製して、今月分の下書きを作る

月次ニュースレターのように、毎回ほぼ同じデザインで配信する場合は、過去のキャンペーンを複製して下書きを用意する運用が向いています。

# 1. 先月のキャンペーンを複製して、今月分の下書きを作る
curl -X POST "<your-api-base-url>/api/email/campaign/{先月のキャンペーンID}/duplicate" \
  -H "X-API-Key: $BENCHMARK_KEY" \
  -H "User-Agent: MonthlyNewsletter/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "name": "2026年11月号ニュースレター" }'

# 2. 件名・プレビューテキスト・送信先リストを更新する（__v は直前に取得した値）
curl -X PATCH "<your-api-base-url>/api/email/campaign/{新しいキャンペーンID}" \
  -H "X-API-Key: $BENCHMARK_KEY" \
  -H "User-Agent: MonthlyNewsletter/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "【11月号】今月のお知らせ",
    "previewText": "新機能と活用事例をまとめました",
    "lists": ["{送信先リストID}"],
    "__v": 0
  }'

あとは、Benchmark Emailの画面で下書きを開き、本文を書き換えて、内容を確認してから配信します。「下書きの準備」までをAPI、「最終チェックと送信」を人間という分担にすると、安全に運用できます。

例5：AIコーディングアシスタントに実装を任せる

公式の開発者ドキュメントは、AIコーディングアシスタント向けの資料も用意しています。

• llms.txt：全ドキュメントページの目次
• llms-full.txt：全ドキュメントの全文を1ファイルにまとめたもの
• SKILL.md：エンドポイント、判断の指針、よくあるミスをまとめた、エージェント向けの手引き

AIに依頼するときは、「まずSKILL.mdを読んで、次にやりたいことに対応するシナリオガイドを読んでから、コードを書いてください」と指示するのがおすすめです。たとえば前述の例1のようなGoogle Apps Scriptも、仕様をAIに読ませたうえで「うちのスプレッドシートの列構成に合わせて書いて」と頼めば、短時間で自分用に調整できます。

実装するときの注意点

シナリオガイドから拾った、ハマりやすいポイントをまとめます。

• PUTは「全置き換え」：連絡先をPUTで更新すると、リクエストに含めなかった項目は消えます。先にGETで最新のデータを取得し、それを土台に変更したい部分だけ書き換えて送ります
• __v（バージョン）が必須：PUTやキャンペーン・リストのPATCHでは、直前にGETで取得した__vを付ける必要があります。古い値だと ConcurrencyError（400）になるので、再取得してやり直します
• ステータスは大文字小文字を区別する：Active、Inactive、Unsubscribe はこの表記のままで送る必要があり、小文字だとエラーになります。Inactive にするときは primary と secondary の両方が必須です
• 配信停止やバウンスの連絡先は戻せない：一度 Inactive になった連絡先は、APIでは Active に戻せません。コンプライアンス保護のための仕様なので、勝手に復活させようとしないのが大前提です
• 重複はエラーになる：同じ構造内に同じメールアドレスがあると DuplicateFieldError が返ります。作成前に検索で確認するか、エラーを見て更新に切り替えます
• 検索の source は必須：返してほしい項目を _id、key、fields などの配列で指定します。値は大文字小文字を区別し、未知の値が1つでもあるとリクエスト全体が拒否されます
• 連絡先の一覧取得はページングなし：GET /api/contact は一度に全件を返すので、件数が多いアカウントでは、ページングのある検索APIのほうが安全です
• 送信元アドレスは認証済みドメインのものだけ：キャンペーンの from は、認証済みの送信ドメインのアドレスである必要があります
• キーは必ず環境変数やスクリプトプロパティで管理する：ソースコードやスプレッドシートのセルに直書きしないでください。漏えいが疑われたら、キーを無効化・再生成します

Benchmark Email APIのメリットと注意点

どんな人に向いているか

向いている人

• ECサイト・予約システム・CRM・スプレッドシートなど、複数の場所に顧客データがあり、手作業での名寄せに時間を使っている
• 開発者がいる、またはAIコーディングツールに実装を任せられる
• 配信結果を自分のダッシュボードやBIツールで見たい
• 毎月ほぼ同じ形式のメールを、下書きの準備だけ自動化したい

向いていない人

• Benchmark Emailの画面だけで運用が完結しており、外部ツールとの連携が不要
• 完全なノーコードで、クリックだけで連携を設定したい（現時点では、Zapierなどの外部ツールにHTTPリクエストを組み込む形になる）
• APIからメールの送信そのものを実行したい（トランザクションメール的な用途には向かない）

よくある質問（FAQ）

Q. Benchmark Emailの無料プランでもAPIは使えますか？

はい。APIは全プランに無料で含まれています。無料プランではアクティブなAPIキーを2つまで作れます。

Q. プログラミングの知識がなくても使えますか？

連携用のコードを書く、または生成する必要があります。自分でコードを書けなくても、開発者に依頼するか、AIコーディングアシスタントを使えば実現できます。

Q. APIでメールを送信できますか？

直接はできません。キャンペーンの作成・設定・複製までがAPIで、スケジュール設定や送信はBenchmark Emailの画面で行います。

Q. APIキーはどこで作成できますか？

オーナー権限のアカウントで、Settings > API Keys から作成できます。キーは作成時の1回しか表示されないため、必ずその場で控えてください。

Q. レート制限はどのくらいですか？

開発者ドキュメントでは、1アカウントあたり3,600リクエスト/時（複数キーの合計）で、月間クォータは連絡先上限の10倍（無料）または100倍（有料）とされています。数値は変更される可能性があるため、最新情報はドキュメントの「Rate Limits」で確認してください。

Q. Googleスプレッドシートと連携できますか？

公式のコネクタはありませんが、Google Apps Scriptから UrlFetchApp でAPIを呼べば連携できます。この記事の例1・例2のように、スプレッドシートからの連絡先登録や、配信結果の書き出しが可能です。

まとめ

Benchmark Email APIは、連絡先・リスト・キャンペーン・レポート・送信ドメインを外部ツールとつなげるための、全プラン無料のAPIです。

• 連絡先の同期・検索・重複チェック、リスト管理、レポートの取得など、「データの出し入れ」にかかる手作業を自動化できる
• 一方で、送信・スケジュール・最終的なデザインはAPIでは扱えず、安全のために画面での確認が残る
• 使うには、開発者かAIツールの助けが必要だが、公式がllms.txtやSKILL.mdを用意しているため、AIに実装を任せる前提なら敷居は高くない
• Googleスプレッドシートとは、Google Apps Scriptを使えば、申込者リストの自動登録や配信成果の自動集計ができる

まずは無料プランのAPIキーを1つ作り、GET /api/contact-structure を叩いて、自分のアカウントの構造を確認するところから始めてみてください。そこから、スプレッドシートの同期など、いちばん手間のかかっている作業を1つ自動化するのがおすすめです。

参考リンク

• Benchmark Email API（公式機能ページ）