ローコードプラットフォームSPIRALのAPIを利用する（メール配信機能の使い方）

SPIRALは、主にエンタープライズ向けのローコードプラットフォームになります。ローコードプラットフォームなので、プログラミング知識がなくともWebアプリケーションを開発できるのが魅力です。

SPIRALでは、自社のシステムや外部システムと連携する場合を想定して、APIが公開されています。今回は、そのAPIを利用して、メール配信を行う流れを解説します。

注意点

SPIRALでは、SPIRAL内部で動作するアカウント内APIと、外部APIの2種類があります。アカウント内APIでは、簡単に操作できるPHP SDKがありますが、外部公開はされていません。そのため、今回はPHPの file_get_contents などを使ってAPI操作をしています。

また、メール配信を行う際には、SPIRALの管理画面で送信ドメインの登録やSPF/DKIMの設定を行ってください。

送信ドメイン管理 SPIRAL ver.1 サポートサイト

準備

APIトークンの取得

SPIRALの管理画面で、APIトークンを作成します。ダッシュボードの開発メニュー内のAPIトークンにて、新しいAPIトークンを作成します。

作成後に入手できるAPIトークンと、APIトークンシークレットをメモしておきます。

データベースの作成

今回作成したのは通常DBになります。SPIRALでは、この他8種類のデータベースが利用できます。

【機能紹介】各種DB | SPIRAL ナレッジサイト

データベースの名前は mailmagazine_db としました。作成したフィールドはメール会員管理（ID/パスワード管理） SPIRAL ver.1 サポートサイトに記載の通りです。フィールドは以下の通りです。

フィールド名	サンプル値	型	差し替えキーワード
お名前	テキスト30文字前後	テキストフィールド(64 bytes)	name
メールアドレス	[e-mail]	メールアドレス（大・小文字を無視）	mail
パスワード	半角英数字10桁前後	メッセージダイジェスト(SHA256)	password
都道府県	プルダウンから選択	都道府県	pref
性別	男性、女性	性別	gender
血液型	A型、B型、O型、AB型、不明	セレクト	bloodType
登録日時	yyyy年mm月dd日hh時mm分ss秒	登録日時	registDate
更新日時	yyyy年mm月dd日hh時mm分ss秒	日付（○年○月○日 ○時○分○秒）	lastUpdate
不正アドレスフラグ	不正アドレスフラグ	不正アドレスフラグ	invalidEmail
モバイルドメインフラグ	モバイルドメイン	モバイルドメインフラグ	mobileFlg
重複フラグ	重複フラグ	重複フラグ	duplicateFlg
配信エラーカウント	配信エラーカウント	配信エラーカウント	errorCount
オプトアウト	オプトアウト	オプトアウト	stop
変更・停止キー	英数ランダム16桁	簡易パスワード	authKey
ユーザーエージェント	ユーザーエージェント	テキストフィールド(128 bytes)	userAgent

コードについて

今回はPHPで作成しています。

APIトークンの保存

APIトークンとシークレットは、環境変数に保存します。以下のように .env ファイルを作成し、トークンを保存します。

API_TOKEN=your_api_token
API_TOKEN_SECRET=your_api_token_secret

.env の読み込みは vlucas/phpdotenv を使っています。インストールは composer で行います。

composer require vlucas/phpdotenv

次に、PHPのコード内で .env を読み込みます。

require_once __DIR__ . "/vendor/autoload.php";

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

APIリクエストURLの取得

APIでリクエストするURLは、以下の手順で取得します。

// ロケータのURL (変更の必要はありません)
$locator = "https://www.pi-pe.co.jp/api/locator";

// スパイラルの操作画面で発行したトークンを設定します。
$TOKEN = $_ENV['API_TOKEN'];
$SECRET = $_ENV['API_TOKEN_SECRET'];

// API用のHTTPヘッダ
$api_headers = array(
    "X-SPIRAL-API: locator/apiserver/request",
    "Content-Type: application/json; charset=UTF-8",
);

// 送信するJSONデータを作成
$parameters = array();
$parameters["spiral_api_token"] = $TOKEN; //トークン

// 送信用のJSONデータを作成します。
$json = json_encode($parameters);

// curlライブラリを使って送信します。
$curl = curl_init($locator);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $json);
curl_setopt($curl, CURLOPT_HTTPHEADER, $api_headers);
curl_exec($curl);

// エラーがあればエラー内容を表示
if (curl_errno($curl)) echo curl_error($curl);
$response = curl_multi_getcontent($curl);
curl_close($curl);
$response_json = json_decode($response, true);

// サービス用のURL
$APIURL = $response_json['location'];

この時のレスポンスは以下のようになっています。詳細はSPIRAL ver.1 API リファレンスにて確認してください。

{
  "code": 0,
  "message": "OK",
  "location": "https://（APIサーバ）/api/service",
  "default_version": 2,
  "supported_version": [1, 2],
  "use_client_crt": "f"
}

location にAPIサーバのURLが入っています。

メールアドレスの新規登録

作成したデータベースに対して、データを新しく登録します。新規登録する際には、 data パラメータに対して必要な情報を設定します。

// リクエストデータを作成
$parameters = array();
$parameters["spiral_api_token"] = $TOKEN; //トークン
$parameters["db_title"] = "mailmagazine_db"; //DBのタイトル
$parameters["passkey"] = time(); //エポック秒

// 登録したいデータを設定します（１件分）
$parameters["data"] = array(
    array("name" => "registDate", "value" => "now"),
    array("name" => "mail", "value" => "[e-mail]"),
    array("name" => "name", "value" => "Your Name"),
    array("name" => "password", "value" => 'your_password'),
);

// 署名を付けます
$key = $parameters["spiral_api_token"] . "&" . $parameters["passkey"];
$parameters["signature"] = hash_hmac('sha1', $key, $SECRET, false);

// JSON形式にエンコードします
$json = json_encode($parameters);

// curlライブラリを使って送信します。
$curl = curl_init($APIURL);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $json);
curl_setopt($curl, CURLOPT_HTTPHEADER, $api_headers);
curl_exec($curl);

// エラーがあればエラー内容を表示
if (curl_errno($curl)) echo curl_error($curl);
$response = curl_multi_getcontent($curl);
curl_close($curl);

print_r(json_decode($response, true));
?>

レスポンスは以下のようになります。

{
  "code": "0",
  "id": "4",
  "message": "OK"
}

メールの配信予約を行う

メールの配信予約を行う際には、 deliver_express2/regist/request というヘッダーでのリクエストを行います。指定するパラメータは以下の通りです。

キー	コメント
db_title	データベースのタイトル
mail_field_title	メールフィールド
reserve_date	送信日時 (now は即時配信)
subject	サブジェクト
body_text	メール本文
from_name	差出人名
from_address	差出人アドレス
optout_field_title	オプトアウトフィールドのタイトル
dkim_selector	DKIMセレクター名。作成者署名で配信する場合は必ず指定してください。

コードは以下のようになります。

// API用のHTTPヘッダ
$api_headers = array(
    "X-SPIRAL-API: deliver_express2/regist/request",
    "Content-Type: application/json; charset=UTF-8",
);

// 送信するJSONデータを作成
$parameters = array();
$parameters["spiral_api_token"] = $TOKEN;
$parameters["passkey"] = time();
$parameters["db_title"] = "mailmagazine_db";
$parameters["mail_field_title"] = "mail"; //メールフィールド
$parameters["reserve_date"] = "now"; //送信日時(nowは即時配信)
$parameters["subject"] = "APIからメール配信のテスト"; //サブジェクト
$parameters["body_text"] = "テストメールです。\nメールの本文です。"; //メール本文
$parameters["from_name"] = "テストプログラム"; //差出人名
$parameters["from_address"] = "[e-mail]"; //差出人アドレス
$parameters["optout_field_title"] = "stop"; //オプトアウトフィールドのタイトル
$parameters["dkim_selector"] = "D20240201-test"; //DKIMセレクター名。作成者署名で配信する場合は必ず指定してください。

// 署名を付けます
$key = $parameters["spiral_api_token"] . "&" . $parameters["passkey"];
$parameters["signature"] = hash_hmac('sha1', $key, $SECRET, false);

// 送信用のJSONデータを作成します。
$json = json_encode($parameters);

// curlライブラリを使って送信します。
$curl = curl_init($APIURL);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $json);
curl_setopt($curl, CURLOPT_HTTPHEADER, $api_headers);
curl_exec($curl);

// エラーがあればエラー内容を表示
if (curl_errno($curl)) echo curl_error($curl);
$response = curl_multi_getcontent($curl);
curl_close($curl);

// 画面に表示
print_r(json_decode($response, true));

レスポンスは以下のようなJSONです。

{
  "code": 0,
  "message": "OK",
  "rule_id": 1
}

そして、メールが適切に届きます。

まとめ

今回はSPIRALのAPIを利用して、メール配信機能を利用する流れを紹介しました。外部からメール内容を指定して送信処理を行ったり、データベースにあるデータを作成、更新できます。

なお、1分あたりのAPIのリクエスト数は、契約によって上限があります。ご注意ください（詳細はAPIのリクエスト数制限を知りたい SPIRAL ver.1 サポートサイトにて）。

API SPIRAL ver.1 サポートサイト