AWS Pinpoint メール配信までの使い方ざっくりメモ

[AWS Pinpoint](https://aws.amazon.com/pinpoint/)はカスタマーエンゲージメントを目的としたシステムの統合プラットフォームです。
メッセージ配信と分析でそれぞれ別のシステムを開発、連携することなく、全てをAmazon Pinpointに統合して管理、運用することができます。
開発者だけではなくマーケティング担当者の利用も想定しているため、分析結果をグラフィカルに表示する機能もついているのがすごいところですね。

とりあえずどんなもんなのかなーというのが気になったので、ちょろっと触ってみたという個人的なメモです。
簡単に実施できそうかなという理由でメール配信を行う場合を試してみます。
設定の大まかな流れは[メール配信設定のチュートリアル](https://docs.aws.amazon.com/pinpoint/latest/developerguide/tutorials-email-prefs.html)に従って実施しますが、リソース作成は[AWS CLI](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/pinpoint/index.html)を利用して実施していきます。

AWS CLIは以下のバージョンを利用しています。

```shell
$ aws --version
aws-cli/2.0.48 Python/3.7.4 Darwin/19.6.0 exe/x86_64
```

# プロジェクトの設定
まずは管理のベースとなるプロジェクトの設定を行います。

## 1. プロジェクトの作成
まずはプロジェクトを作ります。プロジェクト作成には[create-app](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/pinpoint/create-app.html)を実行します。

```shell
$ json=$(cat << EOS
{
  "CreateApplicationRequest": {
    "Name":"<project_name>"
  }
}
EOS
)
$ aws pinpoint create-app --cli-input-json "$json"
```

Nameがプロジェクト名です。以降の操作で`ApplicationId`を求められることがありますが、この場合はここで指定した名前ではなく自動的に割り当てられたIDの方を指定する形になります。

create-appに限らず、PinpointのCLIは`--cli-input-json`オプションをつけることでJSON形式で設定値を渡すことができます。
`--generate-cli-skeleton`オプションをつけることでリソースを作成せずに設定用JSONのスケルトンだけを出力することも可能です。

## 2. Emailチャネルの有効化
続いてメール配信が出来るようにEmailチャネルを有効化します。
有効化には[update-email-channel](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/pinpoint/update-email-channel.html)を実行します。

```shell

$ json=$(cat << EOS
{
  "ApplicationId": "<project_id>",
  "EmailChannelRequest": {
    "Enabled": true,
    "FromAddress": "<default_sender_address>",
    "Identity": "arn:aws:ses:<region>:<account_id>:identity/<email_address_or_domain>"
  }
}
EOS
)
$ aws pinpoint update-email-channel --cli-input-json "$json"
```

| 項目 | 型 | 用途 |
|:--|:-:|:--|
| Enabled | true / false | trueを設定するとEmailチャネルを有効化します。 |
| FromAddress | string | メール送信時のデフォルト送信元アドレスを設定します。 |
| Identity | string | メール送信時に利用するAmazon Simple Email Serviceの[Amazon Resource Name](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html)を設定します。identity/の後ろにドメインを指定した場合はそのドメインの任意のメールアドレスから送信可能です。 |

今回はお試しなので`Identity`にはメールアドレスを設定しました。

`FromAddress`に設定したメールアドレスには利用確認メールを送る必要があります。
裏側ではメール送信に[Amazon Simple Email Service (SES)](https://aws.amazon.com/ses/)を使っているようで、SESの操作である[create-email-identity](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sesv2/create-email-identity.html)を実行して確認メールを送信できます。


```shell
$ aws sesv2 create-email-identity --email-identity <default_sender_address>
```

このメールに記載されているURLへアクセスすることで送信元アドレスとして利用可能になるようです。

また、Emailチャネルの場合、作成直後は不正使用から保護するためにサンドボックス環境としてセットアップされるようです。
https://docs.aws.amazon.com/pinpoint/latest/userguide/tutorials-send-an-email-upload-contacts.html
> If this is your first time using Amazon Pinpoint, your account is in the sandbox. When your account is in the sandbox, you can only send email to verified identities. 

この状態では検証済みメールアドレスのみ送受信が可能です。（テストメール送信機能を行う場合は任意のアドレスでも受信のみ可）
このサンドボックス環境も[SESが持っている機能](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/request-production-access.html)のようです。必要な手続きを行うことで本番運用環境へ移行できます。

# Email送信の設定
メール送信を行うには以下を作成する必要があります。
1. エンドポイント: 実際の送信先
2. セグメント: まとめて通知する集団（複数のエンドポイントの集まり）
3. メールテンプレート: 送信するメール内容のテンプレート
4. キャンペーン: メール送信を行う単位

全体像としては以下のような感じです。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/222603/79f52398-911f-4f67-2d1d-59571fc30f50.png)



## 1. エンドポイントの作成
エンドポイントの作成には[update-endpoint](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/pinpoint/update-endpoint.html)を実行します。

```shell
$ json=$(cat << EOS
{
  "ApplicationId": "<project_id>",
  "EndpointId": "<endpoint_name>",
  "EndpointRequest": {
    "Address": <recipient_address>,
    "ChannelType": "EMAIL"
  }
}
EOS
)
$ aws pinpoint update-endpoint --cli-input-json "$json"
```

ChannelTypeにEMAILを指定することで、このエンドポイントを利用した時はメールが使われるようになります。
たくさん作成するときは[update-endpoints-batch](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/pinpoint/update-endpoints-batch.html)を利用したり、S3にアップロードした設定ファイルを読み込んで作成する方法を選択した方が良さそうです。

## 2. セグメントの作成

セグメントの作成には[create-segment](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/pinpoint/create-segment.html)を実行します。

```shell
$ json=$(cat << EOS
{
  "ApplicationId": "<project_id>",
  "WriteSegmentRequest": {
    "Dimensions": {
      "Demographic": {
        "Channel": {
          "DimensionType": "INCLUSIVE",
          "Values": ["EMAIL"]
        }
      }
    },
    "Name": "<segment_name>"
  }
}
EOS
)
$ aws pinpoint create-segment --cli-input-json "$json"
```

例としてChannelTypeがEMAILのエンドポイントを対象とするセグメントを作成します。
対象とするエンドポイントの条件を細かく設定したりセグメントのグルーピング設定を行うことでメール送信後により細かい分析ができるようになりそうですが、とりあえずシンプルなルールで作ってみます。

## 3. メールテンプレートの作成

メールテンプレートのの作成には[create-email-template](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/pinpoint/create-email-template.html)を実行します。

```shell
$ json=$(cat << EOS
{
  "EmailTemplateRequest": {
      "HtmlPart": "<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\" />\n</head>\n<body>\n<p>Hi!</p>\n<p style=\"color:red;\">This is sent from my first Amazon Pinpoint!</p>\n</body>\n</html>",
      "Subject": "Hello, Amazon Pinpoint!",
      "TemplateDescription": "My first template.",
      "TextPart": "Hi! \nThis is sent in plain text from my first Amazon Pinpoint!"
  },
  "TemplateName": "<template_name>"
}
EOS
)
$ aws pinpoint create-email-template --cli-input-json "$json"
```

| 項目 | 型 | 用途 |
|:--|:-:|:--|
| HtmlPart | string | HTMLメールの本文を設定します。 |
| Subject | string | メールのタイトルを設定します。 |
| TemplateDescription | string | （任意）テンプレートの説明を設定します。 |
| TextPart | string | （任意）テキストメールのみを受け付けている場合の本文を設定します。 |
| TemplateName | string | テンプレート名を設定します。 |

以下のようなメールが送られる想定のテンプレートを作成してみました。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/222603/6de9cf78-2d0e-1dd5-1fa3-fb64703b2a50.png)


## 4. キャンペーンの作成

キャンペーンの作成には[create-campaign](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/pinpoint/create-campaign.html)を実行します。
以下の例ではキャンペーンを作成したらすぐにメールを送信します。


```shell
$ json=$(cat << EOS
{
  "ApplicationId": "<project_id>",
  "WriteCampaignRequest": {
    "Name": "<campaign-name>",
    "Schedule": {
      "IsLocalTime": false,
      "StartTime": "IMMEDIATE",
      "Timezone": "UTC"
    },
    "SegmentId": "<segment_id>",
    "SegmentVersion": <segment_version>,
    "TemplateConfiguration": {
      "EmailTemplate": {
        "Name": "<email_template_name>"
      }
    }
  }
}
EOS
)
$ aws pinpoint create-campaign --cli-input-json "$json"
```

主な設定は以下です。

| 項目 | 型 | 用途 |
|:--|:-:|:--|
| Schedule.StartTime | string | キャンペーンの開始タイミングを設定します。IMMEDIATEを指定すると即時で実行されます。 |
| SegmentId | string | 送信対象セグメントのIDを設定します。セグメントのIDはコンソール上から確認できる他、[get-segments](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/pinpoint/get-segments.html)で一覧を取得することでも確認できます。 |
| SegmentVersion | string | 送信対象セグメントのバージョンを設定します。 |
| EmailTemplate.Name | string | 利用するメールテンプレート名を設定します。 |

設定するとセグメントに含まれるエンドポイント全てに対してメールが送信されます。

# 送信結果の確認

Amazon Pinpoint Console上からキャンペーンのメール送信結果を確認できます。
試しに2件送って1件だけ開封した結果が以下です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/222603/a8f4142e-8715-c4ef-bcad-683132b6af1a.png)

送られてきたメールをみてみると、開封は本文に1×1pxのdisplay:noneなimageタグを埋め込むことで検知しているようです。
imageタグのsrcのURLにはメールヘッダの`Message-ID`を含んでいたので、それを元によしなに突合して……いるのかどうかまではわかりませんが、このURLへのアクセスでカウントしてくれているっぽいです。
開封確認の方法としてはよくある形式ですね。

メール開封率などの指標は[get-campaign-date-range-kpi](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/pinpoint/get-campaign-date-range-kpi.html)を実行して取得することも出来ます。

```shell
$ json=$(cat << EOS
{
    "ApplicationId": "<project_id>",
    "CampaignId": "<campaign_id>",
    "KpiName": "email-open-rate",
    "StartTime": "1970-01-01T00:00:00",
    "EndTime": "1970-01-01T00:00:00"
}
EOS
)
$ aws pinpoint get-campaign-date-range-kpi --cli-input-json "$json"
```

`KpiName`に取得したい指標を指定して取得する形です。設定可能な値は[公式ドキュメント](https://docs.aws.amazon.com/pinpoint/latest/developerguide/analytics-standard-metrics.html)にまとまっています。

---

今回はエンドポイント等に細かい情報をまったく設定しなかったため単純なメール送信と結果確認だけでした。
ただ、適切に設定することでより柔軟にターゲットを指定してメールを送信したり、詳細な分析ができるものと思います。
また、設定次第でメールに記載されたリンクへ遷移した後のファネル分析も行えるようです。
自前で分析システムを構築しなくても分析が出来るのは1つのメリットかなと思いました。