【FileMaker】SendGrid経由でメールを送る - 日時指定でキャンペーンメールを送る

# 今までのSendGrid応用編
この回は、2021年のAdventCalendar向けにシリーズとしてお届けしていました。
実に1年経ってしまいましたが、改めて前回までの記事を時系列で紹介します。
[【FileMaker】SendGrid経由でメールを送る - 一括送信編](https://qiita.com/tyuma/items/00af3bb5a1e9508404bc)
[【FileMaker】SendGrid経由でメールを送る - テンプレートを使う](https://qiita.com/tyuma/items/a5a4a47aa5dfb7df95bd)

これまでの基本的なSendGridメール送信については、以下の記事もぜひ参考にしてみてください。

[【FileMaker】SendGrid経由でメールを送る 下準備編](https://qiita.com/tyuma/items/42b415fb9c515ff1b0d8)
[【FileMaker】SendGrid経由でメールを送る テキストメール編](https://qiita.com/tyuma/items/778b94db943b0e3ba713)
[【FileMaker】SendGrid経由でメールを送る 添付ファイル編](https://qiita.com/tyuma/items/e9c7f113af3794305ad6)
[【FileMaker】SendGrid経由でメールを送る - エラーコード10が返ってくる](https://qiita.com/tyuma/items/24511733d9d72807c653)

では、おさらいが済んだところで、今回の記事、進めましょう！

# FileMaker バージョン
curlとJSONを使いますので、FileMaker ver.16以上で実装してみてください。
この記事では、FileMaker ver.19.6.1で作成し、実行しました。

気がつきましたが、去年はver.19.4.1で作成していました。
1年で0.2バージョン上がったんですね！
進化の早い FileMaker !

# 現場の疲弊

さて、営業や現場スタッフの尽力で、おかげさまで購入数やユーザ数も増えてきました。
今まではキャンペーンのお知らせを手で作って夜中に送信していたのですが、流石に働き方改革をしないとスタッフも疲弊してしまいそうです。
そこで、時間指定をしてキャンペーンメールを送れるようにしよう、となりました。

まず、SendGridのキャンペーンメールについて、事前に知識を入れておきましょう。

# SendGrid キャンペーンメールの概要
以下のサイトが、SendGridキャンペーンメール送信に関する情報です。

https://sendgrid.kke.co.jp/docs/API_Reference/Web_API_v3/Marketing_Campaigns/index.html

API仕様は公開されていますが、キャンペーンメールを作成する手順などは、SendGridアカウントを作成して確認してください。

手順として、以下のような流れになります。

1.送信者情報を作成する
2.受信者情報を登録する
3.受信者のグループを作成する
4.メール内容を作成する 
<font color="red">5.送信日時を設定する</font> <-今回の記事

これら手順でAPIが用意されていますが、今回はすでに4まで作成済みであることとして、「5.送信日時を設定」し、その日時で送信されるかどうかのテストを行います。

ちなみに、1〜5まででどんなAPIを使うか、というと、次のようなAPIになります。

| 順番 | 手順 | API |
|:-:|:-:|:-:|
|  1 | 送信者情報を作成する  | [Sender Identities API](https://sendgrid.kke.co.jp/docs/API_Reference/Web_API_v3/Marketing_Campaigns/sender_identities.html)  |
|  2 | 受信者情報を登録する | [Contacts API](https://sendgrid.kke.co.jp/docs/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html)  |
|  3 | 受信者のグループを作成する | [Contacts API](https://sendgrid.kke.co.jp/docs/API_Reference/Web_API_v3/Marketing_Campaigns/contactdb.html)  |
|  4 | メール内容を作成する  | [Campaigns API](https://sendgrid.kke.co.jp/docs/API_Reference/Web_API_v3/Marketing_Campaigns/campaigns.html)  |
|  5 | 送信日時を設定する  | [Campaigns API](https://sendgrid.kke.co.jp/docs/API_Reference/Web_API_v3/Marketing_Campaigns/campaigns.html)  |

一度、SendGrid内で手動でこれらの手順を確認しておくと、APIを使うときに「あの項目がここにはまるのか」というのがわかりやすくなりますので、ぜひやってみてください。
こちらの公式資料も詳しいです。

https://docs.sendgrid.com/ja/ui/sending-email/how-to-send-email-with-marketing-campaigns

SendGridのキャンペーンメールの手順がわかったところで、早速「手順5」をFileMakerからも送ってみましょう。

# FileMakerの実装

## 必要なSendGrid情報
APIキーのほか、以下が必要になります。

・キャンペーンID
・送信日時

キャンペーンIDは、「手順4」でSendGrid内で作成したキャンペーンメールのIDを取得できます。

### SendGridサイトでキャンペーンIDを確認する
直接SendGridサイトで確認する場合は、キャンペーンメールをクリックして編集画面に行った際にURLから確認できます。
![スクリーンショット 2022-12-22 11.55.42.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/60538/c0ff1e04-7eed-1145-9a5b-67a56e28621b.png)

ちなみに、送信済みのキャンペーンメールは、SendGridの「Campaign」カテゴリで確認できます。
![スクリーンショット 2021-12-14 12.25.47.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/60538/85eb49e2-4122-22dd-ac65-a796d91608c1.png)
このCAMPAIGN NAMEをクリックすると、キャンペーンIDやコンプレッションなどをグラフ化したページで色々確認できます。
このグラフは、昨年キャンペーンメールを送信したときの状態です。
テストなのでほぼゼロが続いていますが、通常この時期だとクリスマスや年末年始向けにキャンペーンの送信やメールからのクリック数などが増える時期ではないでしょうか。
![スクリーンショット 2021-12-14 12.27.25.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/60538/56be46f2-8363-4052-70f2-98cb187e8e0d.png)

### APIでキャンペーンIDを確認する
通常、FileMakerなどアプリから運用する場合は、キャンペーンIDをレコードとして保存しておくのがベストと思います。

キャンペーンIDを取得するAPIの構文は、以下になります。

```
GET https://api.sendgrid.com/v3/campaigns?limit={limit}&offset={offset} HTTP/1.1
```
この構文では全てのキャンペーンIDが返ってきますが、作成日の降順で返ってきますので、最初のキャンペーンIDが最新になります。

また、キャンペーンメールの作成もAPI経由ですると、キャンペーンメール作成APIの返値でキャンペーンIDが確認できます。
今回は触れませんが、[SendGrid キャンペーンメール作成APIページ](https://sendgrid.kke.co.jp/docs/API_Reference/Web_API_v3/Marketing_Campaigns/campaigns.html#Create-a-Campaign-POST)で確認してみてください。

## キャンペーンスケジュールAPIの確認
キャンペーンをスケジュールするAPIの構文は、以下になります。

```
POST https://api.sendgrid.com/v3/campaigns/{campaign_id}/schedules HTTP/1.1
```

指定する送信日時は、UNIXタイムスタンプをJSONで指定します。

```
{
  "send_at": 1489771528
}
```

https://sendgrid.kke.co.jp/docs/API_Reference/Web_API_v3/Marketing_Campaigns/campaigns.html#Schedule-a-Campaign-POST

これを、FileMakerでの構文に直して実装します。

## スクリプト
全体的なスクリプトは、以下の画像になります。
水色部分が必要最低限の実装です。
![スクリーンショット 2022-12-22 11.51.07.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/60538/7690396b-fff6-6b24-57d5-e2f4b2974117.png)


### UNIXタイムスタンプの作成
日本時間を加味したUNIXタイムスタンプを指定するので、協定世界時（UTC）に-9時間の計算を入れます。
他にもUNIXタイムスタンプの作成方法がありますが、今回は単純にUTCから9時間引いています。
```
GetAsNumber ( Timestamp ( Get(日付) ; Time ( 12 ; 0 ; 0 ) ) - Timestamp ( Date ( 1 ; 1 ; 1970 ) ; Time ( 0 ; 0 ; 0 ) )- 60 * 60 * 9  )
```

今回は、当日12時にキャンペーンメールを送りたいので、12時を指定しています。
↓この部分です。
```
Timestamp ( Get(日付) ; Time ( 12 ; 0 ; 0 ) )
```

### URL から挿入 でAPI実行する
[URL から挿入](https://help.claris.com/ja/pro-help/content/insert-from-url.html) スクリプトステップ一文で処理します。
![スクリーンショット 2022-12-22 12.20.33.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/60538/df3a5dbd-3ddd-9f72-94d8-9d7837ffbde8.png)
サンプルなのでキャンペーンIDを直で指定していますが、運用ではレコードの保存した値などを指定してください。
あと、この１行だけだとエラーが返ってきた時の処理を省いていますので、キャンペーンIDの運用同様、エラー処理は実装してください。
よくあるエラーとして、以下があります。

| エラーコード | エラーメッセージ | 弊社的よくある対応 |
|:-:|:--|:--|
| 10  | 要求されたデータが見つかりません  |  返値がない正常終了の可能性があるので、問題ない場合は処理成功とする[^1] |
|  1631 |  接続に失敗しました | API送信先で受け入れられない何かのエラーか、構文が間違えている可能性が高いので要調査。通常、このエラーが出ないようにテストすべし。ただし、API先のシステム障害や仕様変更の可能性もあるので、運用中に出た場合は緊急対応すべしorz  |

エラーコード以外に、返値がターゲットに返ってきます。
今回は、"$getterJson"という変数に入るようにしています。
処理に成功すると、次のようなJSONが返ってきます。
```
{"id":16006868,"send_at":1671678000,"status":"Scheduled"}
```
"status"が"Scheduled"になっているのが確認できます。
無事、キャンペーンメールが指定した日時でスケジュールされたようです！

[^1]: [URL から挿入](https://help.claris.com/ja/pro-help/content/insert-from-url.html) のヘルプも確認してください。

:::note info
エラーコードの一覧は、公式ヘルプで確認してください。
https://help.claris.com/ja/pro-help/content/error-codes.html
:::

# スケジュールされた送信の確認
そうこうするうちに、12時になりました。
メールボックスを見てみましょう。
![スクリーンショット 2022-12-22 12.11.18.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/60538/c808a98b-a617-d214-d4f2-56ecf84e905d.png)
送られてきていました！

SendGridのキャンペーンメール一覧からも、送信済みが確認できます。
![スクリーンショット 2022-12-22 12.36.30.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/60538/1490e9e7-b83d-7875-a73e-d35804ce4073.png)

# Happy Holidays!
これで無事、スタッフも休日をゆっくり過ごせそうですね。
働き方改革の一つにもなっていたら嬉しいですね。