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

[SPIRAL](https://www.spiral-platform.co.jp/)は、主にエンタープライズ向けのローコードプラットフォームになります。ローコードプラットフォームなので、プログラミング知識がなくともWebアプリケーションを開発できるのが魅力です。

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

## 注意点

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

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

[送信ドメイン管理 SPIRAL ver\.1 サポートサイト](https://support.smp.ne.jp/manuals/from_domain_list/)

## 準備

### APIトークンの取得

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


![image2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/197026/437b3d56-f96d-4dd3-90a5-ac30bf9aa91e.png)


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

### データベースの作成

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

[【機能紹介】各種DB \| SPIRAL ナレッジサイト](https://knowledge.spirers.jp/article/design/detail/730)

データベースの名前は `mailmagazine_db` としました。作成したフィールドは[メール会員管理（ID/パスワード管理） SPIRAL ver\.1 サポートサイト](https://support.smp.ne.jp/tips/tips22/)に記載の通りです。フィールドは以下の通りです。

| フィールド名           | サンプル値                 | 型                                 | 差し替えキーワード |
| ---------------------- | -------------------------- | ---------------------------------- | ------------------ |
| お名前                 | テキスト30文字前後         | テキストフィールド(64 bytes)       | name               |
| メールアドレス         | aaa@bbb.cc.dd              | メールアドレス（大・小文字を無視） | 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` ファイルを作成し、トークンを保存します。

```env
API_TOKEN=your_api_token
API_TOKEN_SECRET=your_api_token_secret
```

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

```bash
composer require vlucas/phpdotenv
```

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

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

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

### APIリクエストURLの取得

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

```php
// ロケータの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 リファレンス](https://support.smp.ne.jp/api/index.html#operation/locatorApiserver)にて確認してください。

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

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

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

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

```php
// リクエストデータを作成
$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" => "user@example.com"),
    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));
?>
```

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

```json
{
  "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セレクター名。作成者署名で配信する場合は必ず指定してください。 |

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

```php
// 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"] = "admin@example.com"; //差出人アドレス
$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です。

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

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

![image1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/197026/b9059b8c-1782-41e2-b2a6-0de6d3fad4cb.png)


## まとめ

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

なお、1分あたりのAPIのリクエスト数は、契約によって上限があります。ご注意ください（詳細は[APIのリクエスト数制限を知りたい SPIRAL ver\.1 サポートサイト](https://support.smp.ne.jp/faq/api-faq/f0094/)にて）。

[API SPIRAL ver\.1 サポートサイト](https://support.smp.ne.jp/api-manuals/)