新しくなったActivityを使いこなそう〜Web API編

新しくなったActivityを使いこなそうWeb API編

はじめに

2024年4月、弊社（株式会社構造計画研究所）経由でご契約いただいたTwilio SendGridアカウントのActivity機能がリニューアルされました。先日公開した記事ではダッシュボードの機能の変更点や具体的な検索例を説明しましたが、今回はWeb API経由でメールを検索できる「Email Activity API」の使い方を紹介します。

この4月から、以下の4種類のAPIが利用できるようになりました。

  1. メールを検索して概要情報を取得するAPI（Filter all messages）
  2. 特定のメールの詳細情報を取得するAPI（Filter messages by message ID）
  3. CSVファイルを生成するAPI（Request a CSV）
  4. CSVファイルのダウンロード用API（Download CSV）

このうち、1と2の利用には「Additional Email Activity History」のオプションを申し込む必要があります（有料）。Freeプランではお使いいただけないのでご注意ください。一方、3と4はすべてのプランで利用可能です。

Web APIで取得できる情報は、ダッシュボードで取得できる情報とほぼ同じです。APIの利用を検討している方やこれからAPIを使い始める方は、まずダッシュボードでActivityを試して、取得できる情報のイメージを掴んでおくと良いでしょう。ダッシュボードの操作方法は、チュートリアル、動画、ブログ記事を参照してください。

次の章から4つのAPIをそれぞれ解説していきます。

おすすめメール配信サービス「SendGrid」を始めるメール配信サービス「SendGrid」を始めるGmailガイドライン対応！メルマガ一斉送信もシステム経由の自動通知メールもこれ1つで解決。無料で試してみる

1. メールを検索して概要情報を取得するAPI

条件を指定して検索できるダッシュボードの「Advanced Search」のAPI版で、画面と同等の条件でメールを抽出できます。APIによる絞り込み検索は自由度が高いもののリクエスト方法が複雑なので詳しく説明します。

リクエストとレスポンス

  • メソッド：GET
  • パス：/v3/messages
  • ヘッダ：「Authorization: Bearer APIキー」が必要
  • クエリパラメータ：結果取得件数を指定するlimit（必須）、絞り込み条件を指定するquery（任意）

APIキーには「Email Activity」の権限が必要です。オプション追加後に既存のAPIキーに権限を追加するか、新しくAPIキーを作成しましょう。
cURLで実行する場合、リクエストは以下のようになります。この例では、件名が「Hello, SendGrid!」のメールを10件取得しています。

curl --request GET \
 --url 'https://api.sendgrid.com/v3/messages?limit=10&query=subject%3D%22Hello%2C%20SendGrid!%22' \
 --header 'Authorization: Bearer APIキー'

レスポンスの例を以下に示しました。送信元メールアドレス（from_email）、メールを一意に識別するSendGrid Message ID（msg_id）、件名（subject）、宛先メールアドレス（to_email）、送信完了したかどうかのステータス（status）、開封数（opens_count）、クリック数（clicks_count）、最後にイベントが発生した日時（last_event_time）が記載されます。

{
    "messages": [
        {
            "from_email": "from@example.com",
            "msg_id": "m0RzytOplQtCzfH7mMRyaw.recvd-6a935d235c-l7bth-1-663AEC75-44.0",
            "subject": "Hello, SendGrid!",
            "to_email": "to@example.co.jp",
            "status": "delivered",
            "opens_count": 1,
            "clicks_count": 0,
            "last_event_time": "2024-08-20T04:00:00Z"
        }
    ]
}

絞り込み条件の指定方法

リクエストのクエリパラメータの1つである「query」で絞り込み条件を指定します。上述のリクエスト例では「query=subject%3D%22Hello%2C%20SendGrid!%22」となっています。この値は「subject="Hello, SendGrid!"」をURLエンコードしたものです。まず絞り込みの条件式を構成し、次にそれをURLエンコードし、最後にquery=の後ろに指定することでリクエストできます。

絞り込み条件のキーとして指定できる属性の種類はダッシュボードで指定できるものとほぼ同等です。主なものを以下に記載します。

  • api_key_id（APIキーのID）
  • marketing_campaign_id（マーケティングキャンペーン機能で送信したメールのキャンペーンID）
  • marketing_campaign_name（マーケティングキャンペーン機能で送信したメールのキャンペーン名）
  • categories（送信時に指定できるカテゴリ）
  • last_event_time（そのメールの最後のイベント発生日時）
  • events（そのメールにおいて発生したイベント）
  • from_email（送信元メールアドレス）
  • msg_id（SendGridがメールを一意に識別するための「SendGrid Message ID」）
  • clicks（クリック数）
  • opens（開封数）
  • outbound_ip（送信元IPアドレス）
  • status（メールの送信状況）
  • subject（件名）
  • to_email（宛先メールアドレス）
  • template_id（テンプレートを利用して送信したメールのテンプレートID）
  • asm_group_id（配信停止グループを指定して送信したメールの配信停止グループID）

利用可能な演算子は「=」だけではありません。主要なものを以下に挙げます。

  • 論理演算
    • AND
    • OR
    • NOT
  • 比較、マッチング
    • =
    • !=
    • <
    • >
    • <=
    • >=
    • LIKE
    • BETWEEN
    • CONTAINS
  • 日時関連
    • TIMESTAMP
    • INTERVAL
    • DAY

具体的なユースケースにおける指定例

ここからは、具体的な検索の例を挙げながら、どのようなリクエストを構成すれば良いか紹介していきます。

メールが届いたかどうか確認する

メールが届いたかどうかはstatusで判別できます。delivered（宛先サーバが受理済み）、processing（SendGridが送信処理中）、not_delivered（送信失敗）の3種類を指定できます。「status="not_delivered"」という条件にすれば、送信に失敗したメールを絞り込むことができます。これをURLエンコードすると「status%3D%22not_delivered%22」となるので、それをクエリパラメータ「query」に指定した、以下のURLにリクエストします。以降の例でも同様にURLを記載していきます（ここではlimitは10としています）。

https://api.sendgrid.com/v3/messages?limit=10&query=status%3D%22not_delivered%22
特定の宛先に送信したメールの状況を確認する

宛先の絞り込みにはto_emailを利用します。「to_email="example@example.com"」とすればexample@example.com宛に送ったメールを絞り込めます。

https://api.sendgrid.com/v3/messages?limit=10&query=to_email%3D%22example%40example.com%22

example.comドメインの部分一致で絞り込みたい場合は、LIKE句とワイルドカード（%）を用いて「to_email LIKE "%example.com%"」とします。

https://api.sendgrid.com/v3/messages?limit=10&query=to_email%20LIKE%20%22%25example.com%25%22
特定のイベントが発生したメールを抽出する

開封やクリックなど、特定のイベントが発生したメールを抽出する場合はeventsを利用します。例えば、開封されたメールを絞り込む際は「Contains(events,"open")」とします。

https://api.sendgrid.com/v3/messages?limit=10&query=Contains%28events%2C%22open%22%29

以前のブログでも解説した通り、あくまで新Acticityはイベントではなくメールを検索する機能です。一件のメールには複数のイベントが発生しうるので、「event="open"」とはせずにContainsを使います。

指定できるイベントは、processed、drop、delivered、deferred、bounce、open、click、spamreport、unsubscribe、group_unsubscribe、group_resubscribeです（イベントの意味はドキュメントを参照してください）。
ややこしいのですが、「Contains(events,"bounce")」で絞り込むとソフトバウンス（Blockイベント）とハードバウンス（Bounceイベント）がともに含まれます。いずれか一方が発生したメールを検索したいときは「type="bounce"」もしくは「type="blocked"」と指定してください。

https://api.sendgrid.com/v3/messages?limit=10&query=type%3D%22blocked%22
期間を指定する

last_event_timeを指定すると、最後にイベントが発生した日時で絞り込めます。例えば、日本時間の2024年8月21日00:00から23:59の間に最後のイベントが発生したメールは、「last_event_time BETWEEN TIMESTAMP "2024-08-20T15:00:00Z" AND TIMESTAMP "2024-08-21T14:59:59Z"」と指定します。日時はISOフォーマット（ISO8601）で指定するので、日本時間とは9時間ずれることに注意してください。

https://api.sendgrid.com/v3/messages?limit=10&query=last_event_time%20BETWEEN%20TIMESTAMP%20%222024-08-20T15%3A00%3A00Z%22%20AND%20TIMESTAMP%20%222024-08-21T14%3A59%3A59Z%22

DAYやHOUR等を使えば時間幅を指定できます。「日本時間2024年8月21日00:00の2日前から、8月21日23:59まで」を指定するには「last_event_time BETWEEN TIMESTAMP "2024-08-20T15:00:00Z" - INTERVAL 2 DAY AND TIMESTAMP "2024-08-21T14:59:59Z"」とします。

https://api.sendgrid.com/v3/messages?limit=10&query=last_event_time%20BETWEEN%20TIMESTAMP%20%222024-08-20T15%3A00%3A00Z%22%20-%20INTERVAL%202%20DAY%20AND%20TIMESTAMP%20%222024-08-21T14%3A59%3A59Z%22

期間の終わりを明示せずに「日本時間2024年8月21日00:00以降」と指定したい場合は、不等号を用いて「last_event_time > TIMESTAMP "2024-08-20T15:00:00Z"」とします。

https://api.sendgrid.com/v3/messages?limit=10&query=last_event_time%20%3E%20TIMESTAMP%20%222024-08-20T15%3A00%3A00Z%22

なお、「last_event_time」という名前の通り、絞り込み対象になるのはメールの最後のイベントが指定期間に発生している場合です。そのため、「ある特定のイベントが特定の期間に発生したメール」は検索できないので注意してください。

あるテンプレートを利用して、特定の宛先に送信したメールの状況を確認する

ここからは複数の条件を組み合わせた絞り込みの例を紹介します。
ある宛先に特定のテンプレートを使って送信したメールの状況を知りたい場合は、to_emailとtemplate_idをANDで繋いで「to_email="example@example.com" AND template_id="d-3d6312bd9c22f6885464b1379ecf487f"」とすればOKです。

https://api.sendgrid.com/v3/messages?limit=10&query=to_email%3D%22example%40example.com%22%20AND%20template_id%3D%22d-3d6312bd9c22f6885464b1379ecf487f%22
あるキャンペーンで、開封はしたがリンククリックはしていないメールを抽出する

clicksやopensはクリックや開封された回数を表します。マーケティングキャンペーンのIDと組み合わせて「marketing_campaign_id=123456789 AND opens>0 AND clicks=0」とすれば、開封されたがクリックされていないメールを絞り込めます。なお、キャンペーンIDは、ダッシュボードのキャンペーン詳細画面の下部に記載されています。

https://api.sendgrid.com/v3/messages?limit=10&query=marketing_campaign_id%3D123456789%20AND%20opens%3E0%20AND%20clicks%3D0
遅延しているメールの状況を確認する

statusにprocessing（処理中）を、eventsにdeferredを指定すれば、まだ送信処理が完了していないメールのうち、Deferred（遅延）イベントが発生しているメールを抽出できます。この条件式は「status="processing" AND Contains(events,"deferred")」です。

https://api.sendgrid.com/v3/messages?limit=10&query=status%3D%22processing%22%20AND%20Contains%28events%2C%22deferred%22%29
ある2つのカテゴリのいずれかが付与されていて、届かなかったメール

送信時に任意の文字列を指定する「カテゴリ」も、絞り込み検索に利用することができます。カテゴリは1つのメールに複数指定できるので、eventsと同じくContainsを利用します。例えば、カテゴリとして「notification」もしくは「marketing」を指定したメールのうち、届かなかったものを絞り込みたい時は、「(Contains(categories,"notification") OR Contains(categories,"marketing")) AND status="not_delivered"」と指定します。

https://api.sendgrid.com/v3/messages?limit=10&query=%28Contains%28categories%2C%22notification%22%29%20OR%20Contains%28categories%2C%22marketing%22%29%29%20AND%20status%3D%22not_delivered%22

その他の条件の指定例など、詳細は米国のドキュメントも参考にしてください。

2. 特定のメールの詳細情報を取得するAPI

ダッシュボードのActivityでは、検索結果に表示されたメールをクリックすると、発生したイベントを含む詳細な情報を閲覧できます。それと同等の情報を取得できるAPIです。

リクエストとレスポンス

  • メソッド：GET
  • パス：/v3/messages/{msg_id}
  • ヘッダ：「Authorization: Bearer APIキー」が必要
  • パスパラメータ：「SendGrid Message ID」を指定

1のメールを検索して概要情報を取得するAPIで取得できるSendGrid Message ID（msg_idパラメータ）をパスに指定することで、個別のメールの詳細情報を取得します。

curl --request GET \
 --url 'https://api.sendgrid.com/v3/messages/m0RzytOplQtCzfH7mMRyaw.recvd-6a935d235c-l7bth-1-663AEC75-44.0' \
 --header 'Authorization: Bearer APIキー'

レスポンスの例を以下に示します。メールを絞り込むAPIで条件として指定できる各種情報の他、そのメールで発生したイベントの情報も含まれます。eventsの中のreasonパラメータに宛先サーバから返されたSMTPレスポンスが記録されるので、メールが届かなかった際の原因の特定に利用できます。

{
    "from_email": "from@example.com",
    "msg_id": "m0RzytOplQtCzfH7mMRyaw.recvd-6a935d217c-l7bth-1-663AEC75-44.0",
    "subject": "Hello, SendGrid!",
    "to_email": "to@example.co.jp",
    "status": "delivered",
    "template_id": "d-3d6312bd9c22f6885464b1379ecf487f",
    "asm_group_id": 12345,
    "teammate": "",
    "api_key_id": "T4dyg7i0U2QOmknsKV6bw6",
    "events": [
        {
            "event_name": "processed",
            "processed": "2024-08-20T03:30:00Z"
        },
        {
            "event_name": "deferred",
            "processed": "2024-08-20T03:30:03Z",
            "reason": "421 Try again later",
            "mx_server": "mx.example.co.jp"
        },

        {
            "event_name": "delivered",
            "processed": "2024-08-20T03:31:00Z",
            "reason": "250 OK",
            "mx_server": "mx.example.co.jp"
        },
        {
            "event_name": "open",
            "processed": "2024-08-20T04:00:00Z",
            "http_user_agent": "Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0"
        }
    ],
    "originating_ip": "192.0.2.1",
    "categories": ["notification"],
    "unique_args": {"custom_key": "custom_value"},
    "outbound_ip": "198.51.100.1",
    "outbound_ip_type": "dedicated",
    "marketing_campaign_id": null,
    "marketing_campaign_name": null,
    "marketing_campaign_split_id": null,
    "marketing_campaign_version": null
}

3. CSVファイルを生成するAPI

ダッシュボードのActivityには検索結果をCSV形式でエクスポートするボタンがありますが、APIでもCSVファイルを取得できます。CSVファイルの生成をリクエストするAPIとダウンロードするためのAPIの2種類に分かれます。

リクエストとレスポンス

  • メソッド：POST
  • パス：/v3/messages/download
  • ヘッダ：「Authorization: Bearer APIキー」が必要
  • クエリパラメータ：絞り込み条件を指定するquery（任意）

CSVファイルの生成をリクエストするAPIでは、絞り込みを行うAPIと同じ形式の「query」を指定でき、絞り込み結果をCSVファイルとして出力します。以下は、件名が「Hello, SendGrid!」のメールで絞り込んでCSVファイルを生成する例です。

curl --request POST \
 --url 'https://api.sendgrid.com/v3/messages/download?query=subject%3D%22Hello%2C%20SendGrid!%22' \
 --header 'Authorization: Bearer APIキー'

レスポンスは固定です。

{
    "status":"pending",
    "message":"An email will be sent to the address on your profile when the CSV is ready to download."
}

リクエストに成功すると、しばらく待った後に登録メールアドレス宛にSendGridからメールが届きます。ダッシュボードにログインした状態でメール内の「Download」ボタンをクリックすると、イベントデータをCSV形式でダウンロードできます。

4. CSVファイルのダウンロード用API

メール内の「Download」ボタンをクリックして遷移するURLにはdownload_uuidというパラメータがついています。このパラメータを利用すると、API経由でCSVファイルを再ダウンロード可能です。

リクエストとレスポンス

  • メソッド：GET
  • パス：/v3/messages/download/{download_uuid}
  • ヘッダ：「Authorization: Bearer APIキー」が必要
  • パスパラメータ：Download UUIDを指定
curl --request GET \
 --url 'https://api.sendgrid.com/v3/messages/download/089c2634-fd30-144e-1cae-c62d3486857' \
 --header 'Authorization: Bearer APIキー'

レスポンスには、ログインなしでCSVをダウンロード可能なURLが記載されます。

{
    "presigned_url":"https://sendgrid-rts-production-csv-downloads.s3.us-west-2.amazonaws.com/089c2634-fd30-144e-1cae-c62d3486857.csv?XX-Amz-Algorithm=
..."
}

おわりに

今回は、新ActivityをAPI経由で利用する方法について解説しました。ダッシュボードでできるほぼ全ての操作がAPIでも実現できます。メールの送信状況の確認や分析を自動化したい場合などに、ぜひAPIを活用してみてください。
本記事では紹介しきれなかった機能や詳細なパラメータ設定などについては、公式APIリファレンスを参照してください。

おすすめメール配信サービス「SendGrid」を始めるメール配信サービス「SendGrid」を始めるGmailガイドライン対応！メルマガ一斉送信もシステム経由の自動通知メールもこれ1つで解決。無料で試してみる

おすすめ記事

検索

カテゴリ

アーカイブ

メールを成功の原動力に

開発者にもマーケターにも信頼されているメールサービスを利用して、
時間の節約、スケーラビリティ、メール配信に関する専門知識を手に入れましょう。