ファーストビュー画像
ヘッダーロゴ
GitHubアイコン
ホームアイコン
>
ツール
>
【GAS】Benchmark EmailのAPI連携機能を使ってみる
ツール

【GAS】Benchmark EmailのAPI連携機能を使ってみる

作成日2025/03/18
更新日2025/03/25
アイキャッチ
# Benchmark Email
# GAS

目次

今回はメール配信システムであるBenchmark EmailのAPI連携機能を使ってみます。

Benchmark Emailとは

Benchmark Emailとは簡単にHTMLメールの作成・配信を行うことができるサービスです。
メールの作成・配信に加えて送信先のリスト管理・レポート・ランディングページ作成機能などがあります。

無料プランでは登録アドレス500件、月3,500通の送信などが可能です。

参考

Benchmark Emailでは上記の機能に加えて、API・Webhooks機能が提供されており、他サービスと連携することが可能です。

前提として本記事はある程度Benchmark Email, GAS(Google Apps Script)を利用したことがある方向けに書いていますので、各機能の使い方、GASの環境構築については割愛させていただきます。

API連携

API連携機能を実際に使ってみます。

APIキーの確認

API連携機能を使うには認証用のAPIキーが必要になります。

アカウント名をクリックして「連携」ページにアクセスします。

「APIキー」のページで自身のアカウントのAPIキーを確認することができます。

GASの準備

公式の仕様書に従って作成していきます。

GASでBenchmark EmailのAPI用のクラスを作成します。

GASの適当なプロジェクトを作成して以下の内容でコードを記述します。

class benchmarkemailClient {
  constructor(token) {
    this.baseUrl = 'https://clientapi.benchmarkemail.com/'
    this.token = token
  }

  request(path, method='GET', payload=null) {
    const url = this.baseUrl + path
    const options = {
      method: method,
      headers: {
        'Content-Type': 'application/json',
        'AuthToken': this.token
      }
    }

    if (payload) {
      options.payload = JSON.stringify(payload)
    }

    try {
      const response = UrlFetchApp.fetch(url, options)
      const json = JSON.parse(response.getContentText())
      return json['Response']
    } catch (e) {
      // Slackなどに通知するのが望ましい
      console.log(e.message)
    }
  }

  // TODO: 各メソッドを追加
}

内容について軽く説明をします。

クラス定義

class benchmarkemailClient {
  constructor(token) {
    this.baseUrl = 'https://clientapi.benchmarkemail.com/'
    this.token = token
  }
  // 省略
}

Benchmark EmailのAPI用のクラスを定義しています。
このクラス内に各リクエスト処理を追加していき、以下のようにAPIキーを指定して使用できるようにしています。

class benchmarkemailClient {
  constructor(token) {
    this.baseUrl = 'https://clientapi.benchmarkemail.com/'
    this.token = token
  }
  // 省略

  リクエスト処理() {
    // 省略
  }
}

const client = new benchmarkemailClient('APIキー')
client.リクエスト処理

リクエストメソッド

request(path, method = 'GET', payload = null) {
  // 省略
}

リクエストを行うパス、HTTPメソッドの種類、ボディパラメータを引数として受け取るrequestメソッドを定義しています。

各引数の値は公式の仕様書から確認します。

リクエスト処理

APIキーが誤っているなどでエラーが発生した場合はcatchで受け取れるようにしています。

エラーが発生した場合はすぐに気づけるようにSlackなどに通知ができれば理想ですが、今回は一旦ログを表示するのみにしています。

try {
  const response = UrlFetchApp.fetch(url, options)
  const json = JSON.parse(response.getContentText())
  return json['Response']
} catch (e) {
  // Slackなどに通知するのが望ましい
  console.log(e.message)
}

リスト作成

コンタクト(宛先)を格納するためのリストをAPIを使って作成していきます。

公式の仕様書のCreate Listがリスト作成用のAPIです。

リスト作成APIではリスト名に加えて、フィールド項目の設定も可能です。

フィールド項目名は任意のテキスト、フィールドタイプは以下の4種類から選択ができます。

フィールドタイプ

APIで指定する値

全角半角文字/数字

1

数値

2

True / False

3

日付

4

リスト作成処理を追加

クラス内にリストを作成する処理を追加します。

class benchmarkemailClient {
　　// 省略

   // 追加
　　createList(data) {
     return this.request('Contact', 'POST', data)
   }
}

先ほど定義したリクエスト処理にパス(Contact)、HTTPメソッド(今回は作成なのでPOST)、ボディパラメータ(data)を渡しています。

dataは以下のような形式で渡すことを想定しています。
指定できる項目はこちらで確認できます。

{
  Data: {
    Name: "test list",
    Field1Name: "Field 1",
    Field1Type: "2",
    .....
  }
}

リスト作成処理を実行

実際に使ってみます。

以下のテスト用の処理を追加します。

// 省略

function createListTest() {
  const client = new benchmarkemailClient('APIキー')

  response = client.createList({Data: {Name: "APIから作成したリスト"}})
  
  if (!response) return

  if (response["Status"] === "1") {
    console.log(response["Data"])
  } else {
    console.log(response["Errors"])
  }
}

クラスをインスタンス化して、createList関数を実行しています。
APIキーが異なる場合など、リクエスト時に例外が発生した場合はresponseが存在しないため、returnとして処理を終了しています。

リクエスト後のレスポンスは以下のような形式で返ってきます。

{
  "Response": {
    "Data": {
      "Name": "Rest API Creation 1",
      ...
    },
    "Errors": [],
    "Status": "1"
  }
}

リクエストが成功した場合は"Status"が"1"に、同じ名前のリストがすでに存在するなど何かしらのエラーが発生した場合は"Status"が-1になり、"Errors"にエラーメッセージが追加されます。

今回のテスト用の処理では成功した場合は"Data", 失敗した場合は"Errors"の値を出力するようにしています。

実行する関数としてcreateListTestを選択して実行します。

リクエストが成功すると以下のような"Data"の中身が出力されるはずです。

{
  ActiveContactCount: '0',
  CreatedDateTime: '2025年03月18日, 01:45 AM',
  Description: 'APIから作成したリスト',
  # 省略
  Field10Name: '役職名',
  Name: 'APIから作成したリスト'
}

リストのページにアクセスすると新規リストが作成されていることが確認できます。

正しくないAPIキーを指定して実行した場合は以下の内容が出力されます。

Request failed for https://clientapi.benchmarkemail.com returned code 401. Truncated server response: {"detail":"Invalid\/Missing AuthToken in request","status":401,"title":"Invalid Key","token":"invalidapikey"} (use muteHttpExceptions option to examine full response)

すでに作成済みのリストの名前を指定して再度実行した場合は以下の重複した名前であるという以下の内容が出力されます。

[ { Code: '2', Extra: null, Field: 'Name', Message: 'ERROR_NAME_IS_DUPLICATE' } ]

開封レポート

メール開封のレポートを取得してみます。

配信レポートページから確認できる「開封数」に該当するデータを取得することができます。

公式の仕様書のGET Opens Reportがメール開封レポート用のAPIです。

前提

テストメールなどを送信して開封されていることを前提として進めていきます。

開封レポート取得処理を追加

以下の内容で処理を追加します。

class benchmarkemailClient {
　　// 省略

　　createList(data) {
     return this.request('Contact', 'POST', data)
   }

   // 追加
   getOpenReport(emailId) {
     return this.request(`Emails/${emailId}/Report/Opens`)
   }
}

引数としてレポートを取得したい対象のメールのIDを受け取れるようにしています。

メールIDはURLから確認ができます。
Summary?e=xxxxxxxxのxxxxxxxxに該当する部分がメールIDです。

開封レポート取得処理を実行

実際に使ってみます。

以下のテスト用の処理を追加します。

function getOpenReportTest() {
  const client = new benchmarkemailClient('APIキー')

  response = client.getOpenReport('メールID')
  if (!response) return

  if (response["Status"] === "1") {
    console.log(response["Count"])
    console.log(response["Data"])
  } else {
    console.log(response[Error])
  }
}

基本的に先ほどのリスト作成の処理と同じです。

レスポンスは以下のような形式で返ってきます。

{
  Count: 2,
  Data:
    [
      {
        ContactID: '111111111',
        ContactMasterID: '1111111',
        Date: 'Mar 16 2025, 01:58 PM',
        Device: ', ',
        Email: 'user@example.com',
        Name: '未登録 '
      },
      # 省略
    ],
  Error: [],
  IsAutoresponder: '0',
  Name: 'テストメール',
  Status: '1',
  Subject: '件名'
}

"Count"にレポートを開封したアドレスの数、"Data"にそれぞれのアドレスの詳細情報が記載されています。

エラーが発生した場合はリスト作成時は"Errors"でしたが今回は"Error"に値が入るようになっています。

実行する関数としてgetOpenReportTestを選択して実行します。

リクエストが成功すると開封数とそれぞれのアドレスの詳細情報が出力されます。

2
[
  {
    ContactID: '111111111',
    ContactMasterID: '1111111',
    Date: 'Mar 16 2025, 01:58 PM',
    Device: ', ',
    Email: 'user1@example.com',
    Name: '未登録 '
  },
  {
    ContactID: '111111111',
    ContactMasterID: '1111111',
    Date: 'Mar 16 2025, 01:58 PM',
    Device: ', ',
    Email: 'user2@example.com',
    Name: '未登録 '
  },
]

他にも多くのAPIが準備されているのでこれらを活用して大体のことは自動化ができそうです。

share on
xアイコンfacebookアイコンlineアイコン
ホームアイコン
ホーム
同じカテゴリの記事
アイキャッチ
【Cursor×Linear】MCP機能でAIにタスク作成、実装までやってもらう
アイキャッチ
【Salesforce】カスタムメタデータ型を活用して入力規則を作成する