APIを利用してさらにメール配信業務を自動化しよう

本日も、メール配信サービス「ワイメール」の公式コラムをご覧いただき、ありがとうございます。

以前のコラムで、ワイメールが公開しているAPIについて、簡単にご紹介いたしました。その際は、主にAPIの概念や、ワイメールで利用可能なエンドポイント、リファレンスの紹介を行いました。

本記事では、APIを使うことで、より具体的にどのような嬉しいことが起きるのか、例を用いて実践に即した形で解説していきます。

もし、まだAPIがどのようなものかイメージできない方は、一度以下をご一読いただき、本記事に戻ってきてもらうと、より理解が深まるのではないかと思います。

＜Web APIとは？〜ワイメールをもっと便利に使うために〜＞

なお以下に紹介する例において、プログラミングの知識を前提として書いている箇所があります。

ですので、IT担当者以外の方は「とりあえずこのようなことができる」と認識していただき、技術的なところはIT担当者の方に読んでいただくか、一緒に読んでいただけたら効率的かと思います。

1 APIの利用例
- 1.1 利用例 1. 外部システムからワイメールに読者を自動登録
- 1.2 利用例 2. 外部システムからワイメールの会員情報を更新する
2 最後に
3 免責事項

APIの利用例

利用例 1. 外部システムからワイメールに読者を自動登録

現状の運用

自社ホームページに独自に設置した会員登録フォームで会員情報を収集し、それらを後日手動でワイメールに代理登録し、メール配信を行っている状況を想定します。

改善案

APIを利用し、会員登録フォームで登録されたメールアドレスを、自動でワイメールの読者リストに登録します。

クレデンシャルの準備

ワイメールのコントロールパネルにログインし、「共通設定」→「API設定」を開き、「新しいクレデンシャルを作成」をクリックします。

※すでにクレデンシャルが存在する場合は、基本的には、改めて作り直す必要はありません。セキュリティ上の都合や、APIの廃止に伴い、クレデンシャルを削除することができます。削除すると既存のAPI機能が無効となりますので、慎重な取り扱いをお願いいたします。

任意のクレデンシャルの名前を入力し「保存」をクリックします。ここでは例として「api-test」とします。

クレデンシャルが作成され、API Key IDとAPI Secret Keyが自動生成されますので、それらを控えておきます。

「API設定」の画面に戻ります。

Jsonファイルのダウンロード

これは必須ではありませんが、送出パラメタ構築時の参考として、ひな型をダウンロードできます。

必要に応じて、「API設定」の「読者API」セクションにある「add-user」ボタンをクリックし、ダウンロードしたJsonファイルの内容を確認してください。

APIを呼び出す

会員登録フォームを設置している既存システム側で、APIを利用する処理を書きます。API利用時の大まかな流れは以下のようになります。

リクエストデータとAPI Secret Keyから署名を生成
リクエストデータ、API Key ID、署名をエンドポイント対してにAPIリクエストを送出
返却されたデータをチェックし、判定・出力などを行う

詳細な手順は、リファレンスを参照してください。

以下は、javascriptを利用した呼び出し方法の一例です。

なお、このコードはSecret Key IDなどの秘匿情報を含むため、ブラウザがJavascriptを直接実行できる環境にコード配置してしまうと、第三者が閲覧可能となり読者情報の流出や改ざんに繋がります。

実行する場合は、必ず外部公開していないローカルマシン上か、サーバーサイドであればnode.js上などのJavascript実行環境に配置し、第三者がコードを認識できないように注意してください。

const ymladd_result = await this.ymlAddUser();
if(ymladd_result == 'ok'){
  try {
    console.log('読者登録が完了しました。');
  }
  catch(err){
    console.log('読者登録時にエラーが発生しました。');
  }
}
else{
  console.log('読者登録に失敗しました。');
}

async function ymladdUser(){
  // 定数定義
  let result;
  const api_fqdn = 'my-ymail.com'; // ワイメールで利用しているドメイン名
  const method = 'POST';
  const secret_key = '********'; // クレデンシャル作成時に生成されたシークレットキー
  let api_url = 'https://'+ api_fqdn + '/api/rest/v1/add-user/'; // エンドポイント
  var array={
    "apikeyid": "1234567890abcdef",
    "id"  　  : "test",
    "name" 　 : "山田 花子",
    "email" 　: "hanako-yamada@example.jp",
  };
  // 署名を作成
  let query_word = '';
  for (let [key, value] of Object.entries(array)) {
    query_word += '&' + key + '=' + encodeURIComponent(value);
  }
  query_word = query_word.slice(1);
  let sign_word = method + "\n" +api_fqdn + "\n" + end_point + "\n" + query_word;
  const crypto = require('crypto');
  let b64　 = crypto.createHmac('sha256', secret_key).update(sign_word).digest('base64');
  let e_b64 = encodeURIComponent(b64);
　// API呼び出し
  var params = new URLSearchParams();
  for (key in array){
    params.append(key, array[key]);
  }
  params.append('signature', e_b64);
  const axios = require("axios").default;
  try {
    let response = await axios.post(api_url, params.toString(),{
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8'
      }
    });
    // 成功した場合
    if(response.data && !response.data.errors){
      result = 'ok';
    }
    // 失敗した場合
    else{
      result = 'ng';
    }
  }
  catch (err) {
    result = 'ng';
  };
  // 結果返却
  return result;
}

const ymladd_result = await this.ymlAddUser();

if(ymladd_result == 'ok'){

try {

console.log('読者登録が完了しました。');

}

catch(err){

console.log('読者登録時にエラーが発生しました。');

}

else{

console.log('読者登録に失敗しました。');

}

async function ymladdUser(){

// 定数定義

let result;

const api_fqdn = 'my-ymail.com'; // ワイメールで利用しているドメイン名

const method = 'POST';

const secret_key = '********'; // クレデンシャル作成時に生成されたシークレットキー

let api_url = 'https://'+ api_fqdn + '/api/rest/v1/add-user/'; // エンドポイント

var array={

"apikeyid": "1234567890abcdef",

"id" 　 : "test",

"name" 　 : "山田花子",

"email" 　: "hanako-yamada@example.jp",

};

// 署名を作成

let query_word = '';

for (let [key, value] of Object.entries(array)) {

query_word += '&' + key + '=' + encodeURIComponent(value);

}

query_word = query_word.slice(1);

let sign_word = method + "\n" +api_fqdn + "\n" + end_point + "\n" + query_word;

const crypto = require('crypto');

let b64　 = crypto.createHmac('sha256', secret_key).update(sign_word).digest('base64');

let e_b64 = encodeURIComponent(b64);

　// API呼び出し

var params = new URLSearchParams();

for (key in array){

params.append(key, array[key]);

}

params.append('signature', e_b64);

const axios = require("axios").default;

try {

let response = await axios.post(api_url, params.toString(),{

headers: {

'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8'

}

});

// 成功した場合

if(response.data && !response.data.errors){

result = 'ok';

}

// 失敗した場合

else{

result = 'ng';

}

catch (err) {

result = 'ng';

};

// 結果返却

return result;

}

※変数名はあくまで例です。お客様のシステムに合わせて適宜修正してください。

テストを行う

実際にフォームから登録のテストを行い、目的のメルマガに読者登録されているか確認します。

APIから登録が行われた場合、読者の「獲得」には「API」と表示されます。

また、読者の詳細情報を開き、右上の最終更新情報が、「最終更新 YYYY-MM-DD / API “作成したクレデンシャルのAPI Key ID”」となっていることを確認します。

利用例 2. 外部システムからワイメールの会員情報を更新する

現状の運用

こちらのページでご紹介しているような、読者情報に日付型の自由項目である「契約期限」を登録し、ループメールを運用しているものと仮定します。

すなわち、以下のようなループメールを稼働させているものとします。

件名：%%NAME%%様ご契約更新のご案内（1か月前）
配信フィルタの内容：「契約期限(自由項目)」が「今月」

この状態で、ある読者の「契約期限」が「2024-12-31」であれば、2024年の12月1日に、この更新案内メールが自動的に配信されます。

またこの読者が契約更新を行った場合、「契約期限」を「2025-06-30」に修正することで、2025年の6月1日に、同じメールが自動配信されます。

改善案

読者の契約更新は既存システム側で行われるものとします。

既存システム側で、会員の契約期限が更新されたときに、API機能を使って、この読者の「契約期限」が自動更新されるようにします。

クレデンシャルの準備

利用例1.と全く同様の手順です。利用例1.を参照してください。

Jsonファイルのダウンロード

これは必須ではありませんが、送出パラメタ構築時の参考として、ひな型をダウンロードできます。

必要に応じて、「API設定」の「読者API」セクションにある「get-user」ボタンと「update-user」ボタンをクリックし、ダウンロードしたJsonファイルの内容を確認してください。

・get-user_id.json

・update-user_id.json

APIを呼び出す

会員の契約更新処理を行う既存システム側で、APIを利用する処理を書きます。

API利用時の大まかな流れは、利用例1.と同様になりますが、今回の場合は「読者情報の取得」と「読者情報の更新」で計2回、APIを呼び出す必要がある点に注意が必要です。

以下は、javascriptを利用した呼び出し方法の一例です。

// 定数定義
var data = {
  "apikeyid"     : "1234567890abcdef", // クレデンシャルのAPI Key ID
  "secret_key"   : "********",         // クレデンシャル作成時に生成されたシークレットキー
  "api_fqdn"     : 'my-ymail.com',     // ワイメールで利用しているドメイン名
  "id"           : "test",             // 目的のメルマガID
  "email"        : "hanako-yamada@example.jp", // 目的の読者のメールアドレス
  "contract_end" : "2025-06-30",               // 更新後の契約期限
};

// 読者情報の取得
const ymlget_result = await this.ymlGetUser(data);
if(ymlget_result == 'ok'){
  try {
    console.log('読者情報の取得が完了しました。');
      // 読者情報の更新
      const ymlupdate_result = await this.ymlUpdateUser(data);
      if(ymlupdate_result == 'ok'){
        try {
          console.log('読者情報の更新が完了しました。');
        }
        catch(err){
          console.log('読者情報の更新時にエラーが発生しました。');
        }
      }
      else{
        console.log('読者情報の更新に失敗しました。');
      }
  }
  catch(err){
    console.log('読者情報の取得時にエラーが発生しました。');
  }
}
else{
  console.log('読者情報の取得に失敗しました。');
}

async function ymlGetUser(data){
  let result;
  const method = 'POST';
  // エンドポイント
  let api_url = 'https://' + data.api_fqdn + '/api/rest/v1/get-user/';
  // パラメタ作成
  var array={
    "apikeyid" : data.apikeyid,
    "id"       : data.id,
    "email"    : data.email,
  };
  // 署名作成
  let query_word = '';
  for (let [key, value] of Object.entries(array)) {
    query_word += '&' + key + '=' + encodeURIComponent(value);
  }
  query_word = query_word.slice(1);
  let sign_word = method + "\n" + data.api_fqdn + "\n" + '/api/rest/v1/get-user/' + "\n" + query_word;
  const crypto = require('crypto');
  let b64 = crypto.createHmac('sha256', data.secret_key).update(sign_word).digest('base64');
  let e_b64 = encodeURIComponent(b64);
  // API呼び出し
  var params = new URLSearchParams();
  for (key in array){
    params.append(key, array[key]);
  }
  params.append('signature', e_b64);
  const axios = require("axios").default;
  try {
    let response = await axios.post(api_url, params.toString(),{
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8'
      }
    });
    // 成功した場合
    if(response.data && !response.data.errors){
      // ユーザのハッシュを返却
      const uid = Object.getOwnPropertyNames(response.data.data)[0];
      result = uid;
    }
    // 失敗した場合
    else{
      result = 'ng';
    }
  }
  catch (err) {
    result = 'ng';
  };
  # 結果返却
  return result;
}
async function ymlUpdateUser(data){
  let result;
  const method = 'POST';
  let api_url = 'https://' + data.api_fqdn + '/api/rest/v1/update-user/';
  var array = {
    "apikeyid" : data.apikey_id,
    "id"       : data.id,
    "hash"     : data.hash,
    "free_1"   : data.contract_end,
  };
  // 署名作成
  let query_word = '';
  for (let [key, value] of Object.entries(array)) {
    query_word += '&' + key + '=' + encodeURIComponent(value);
  }
  query_word = query_word.slice(1);
  let sign_word = method + "\n" + data.api_fqdn + "\n" + '/api/rest/v1/update-user/' + "\n" + query_word;
  const crypto = require('crypto');
  let b64 = crypto.createHmac('sha256', data.secret_key).update(sign_word).digest('base64');
  let e_b64 = encodeURIComponent(b64);
  // API呼び出し
  var params = new URLSearchParams();
  for (key in array){
    params.append(key, array[key]);
  }
  params.append('signature', e_b64);
  const axios = require("axios").default;
  try {
    let response = await axios.post(api_url, params.toString(),{
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8'
      }
    });
    // 成功した場合
    if(response.data && !response.data.errors){
      result = 'ok';
    }
    // 失敗した場合
    else{
      result = 'ng';
    }
  }
  catch (err) {
    result = 'ng';
  };
  return result;
}

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

// 定数定義

var data = {

"apikeyid" : "1234567890abcdef", // クレデンシャルのAPI Key ID

"secret_key" : "********", // クレデンシャル作成時に生成されたシークレットキー

"api_fqdn" : 'my-ymail.com', // ワイメールで利用しているドメイン名

"id" : "test", // 目的のメルマガID

"email" : "hanako-yamada@example.jp", // 目的の読者のメールアドレス

"contract_end" : "2025-06-30", // 更新後の契約期限

};

// 読者情報の取得

const ymlget_result = await this.ymlGetUser(data);

if(ymlget_result == 'ok'){

try {

console.log('読者情報の取得が完了しました。');

// 読者情報の更新

const ymlupdate_result = await this.ymlUpdateUser(data);

if(ymlupdate_result == 'ok'){

try {

console.log('読者情報の更新が完了しました。');

}

catch(err){

console.log('読者情報の更新時にエラーが発生しました。');

}

else{

console.log('読者情報の更新に失敗しました。');

}

catch(err){

console.log('読者情報の取得時にエラーが発生しました。');

}

else{

console.log('読者情報の取得に失敗しました。');

}

async function ymlGetUser(data){

let result;

const method = 'POST';

// エンドポイント

let api_url = 'https://' + data.api_fqdn + '/api/rest/v1/get-user/';

// パラメタ作成

var array={

"apikeyid" : data.apikeyid,

"id" : data.id,

"email" : data.email,

};

// 署名作成

let query_word = '';

for (let [key, value] of Object.entries(array)) {

query_word += '&' + key + '=' + encodeURIComponent(value);

}

query_word = query_word.slice(1);

let sign_word = method + "\n" + data.api_fqdn + "\n" + '/api/rest/v1/get-user/' + "\n" + query_word;

const crypto = require('crypto');

let b64 = crypto.createHmac('sha256', data.secret_key).update(sign_word).digest('base64');

let e_b64 = encodeURIComponent(b64);

// API呼び出し

var params = new URLSearchParams();

for (key in array){

params.append(key, array[key]);

}

params.append('signature', e_b64);

const axios = require("axios").default;

try {

let response = await axios.post(api_url, params.toString(),{

headers: {

'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8'

}

});

// 成功した場合

if(response.data && !response.data.errors){

// ユーザのハッシュを返却

const uid = Object.getOwnPropertyNames(response.data.data)[0];

result = uid;

}

// 失敗した場合

else{

result = 'ng';

}

catch (err) {

result = 'ng';

};

# 結果返却

return result;

}

async function ymlUpdateUser(data){

let result;

const method = 'POST';

let api_url = 'https://' + data.api_fqdn + '/api/rest/v1/update-user/';

var array = {

"apikeyid" : data.apikey_id,

"id" : data.id,

"hash" : data.hash,

"free_1" : data.contract_end,

};

// 署名作成

let query_word = '';

for (let [key, value] of Object.entries(array)) {

query_word += '&' + key + '=' + encodeURIComponent(value);

}

query_word = query_word.slice(1);

let sign_word = method + "\n" + data.api_fqdn + "\n" + '/api/rest/v1/update-user/' + "\n" + query_word;

const crypto = require('crypto');

let b64 = crypto.createHmac('sha256', data.secret_key).update(sign_word).digest('base64');

let e_b64 = encodeURIComponent(b64);

// API呼び出し

var params = new URLSearchParams();

for (key in array){

params.append(key, array[key]);

}

params.append('signature', e_b64);

const axios = require("axios").default;

try {

let response = await axios.post(api_url, params.toString(),{

headers: {

'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8'

}

});

// 成功した場合

if(response.data && !response.data.errors){

result = 'ok';

}

// 失敗した場合

else{

result = 'ng';

}

catch (err) {

result = 'ng';

};

return result;

}

※変数名はあくまで例です。お客様のシステムに合わせて適宜修正してください。

テストを行う

実際に契約更新のテストを行い、目的の読者の「契約期限」が更新されているか確認します。

右上の最終更新情報が、「最終更新 YYYY-MM-DD / API “作成したクレデンシャルのAPI Key ID”」となっていることを確認します。

最後に

今回は、ワイメールのAPIを使った具体的な活用シーンについて、実際の例を用いて解説いたしました。

所定の形式でAPIにアクセスすれば、リクエストする側の言語や環境を問わずに、必要な情報を正確に得られ、またその情報をアップデートできることがAPIの最大の利点です。

これにより、システムの開発コストを抑えたり、アウトソースしている処理を自社システム内で完結させることが可能です。

ワイメールでは、今後もますます使いやすいサービスとなるよう、また担当者様の手間を一つでも減らして効率的なメール配信アプローチが可能となるよう、改良を重ねてまいります。

免責事項

本コラムで紹介したコードの動作保証は行っておりません。

当コラムの内容は、コラム執筆時点での内容です。今後のバージョンアップ等により、仕様やインターフェイスが変更になる場合がございます。