Email Activity API

Email Activity APIを使うと次の4つの操作ができます。

指定したメッセージIDに該当するEmail Activityのログを取得する
- Filter messages by message ID [GET]
検索条件を指定して、該当するEmail Activityのログを取得する
- Filter all messages [GET]
Email ActivityのログをCSVファイルとして生成する
- Request a CSV [POST]
生成したCSVファイルをダウンロードする
- Download CSV [GET]

上記1と2のAPIを利用するには、オプション「Additional Email Activity History」を追加購入する必要があります。オプションの追加方法は、こちらをご確認ください。

なお、類似機能である「Email Logs API」は無料で利用可能です。Email Logs APIで要件を満たせるかについても、あわせてご検討ください。

Filter messages by message ID [GET]

特定のメールに関するログを取得します。

URI引数	必須	条件	説明
msg_id	Yes	string	取得対象とするメールのメッセージID （SendGrid Message ID）

Request

GET https://api.sendgrid.com/v3/messages/{msg_id} HTTP/1.1

Response

JSONパラメータ	型	制限
from_email	string	メールアドレス
	送信元メールアドレス
msg_id	string
	メッセージID（SendGrid Message ID）
subject	string
	メールの件名
to_email	string	メールアドレス
	宛先メールアドレス
status	string	processing, delivered, not_delivered のいずれか
	メールの送信状況
template_id	string
	使用しているメールテンプレートのID
asm_group_id	integer
	使用している配信停止グループのID
api_key_id	string
	使用しているAPIキーのID
events	オブジェクト配列
	各メッセージに関連するイベントデータから成るオブジェクトの配列
event_name	string	bounce, open, click, processed, drop, delivered, deferred, spamreport, unsubscribe, group_unsubscribe, group_resubscribe のいずれか
	イベント名
processed	string
	イベントが処理された日時
reason	string
	イベントの原因に関する説明
attempt_num	integer
	メールの再送回数（deferredイベント発生時）
url	string
	受信者がクリックしたURL （clickedイベント発生時）
bounce_type	string	blocked, bounce のどちらか
	バウンスの種類（blocked＝ソフトバウンス、bounce＝ハードバウンス）
http_user_agent	string
	メールの開封もしくはクリックをした受信クライアント
mx_server	string
	メールを受信したMXサーバ
originating_ip	string
	メール送信をリクエストした環境のIPアドレス（IPv4）
categories	配列
	メールに関連付けたカテゴリ
unique_args	オブジェクト
	メールに関連付けたユニーク引数
outbound_ip	string
	メールの送信元IPアドレス（IPv4）
outbound_ip_type	string	dedicated, shared のどちらか
	送信元IPアドレスの種類（固定IPアドレスまたは共有IPアドレス）

HTTP/1.1 200
{
    "from_email": "from@example.com",
    "msg_id": "7I0CEvuJTmWxhi_UZ12gmw.recvd-6b888cd74b-k8brp-1-661E6936-10.0",
    "subject": "Hi Hannah, your lucky color is Yellow!",
    "to_email": "hannah@sink.sendgrid.net",
    "status": "delivered",
    "template_id": "",
    "asm_group_id": null,
    "teammate": "",
    "api_key_id": "AuIn2KBETT6BqwgswddGyg",
    "events": [
        {
            "event_name": "processed",
            "processed": "2024-04-16T12:04:06Z"
        },
        {
            "event_name": "delivered",
            "processed": "2024-04-16T12:04:06Z",
            "reason": "250 OK",
            "mx_server": "sink.sendgrid.net"
        }
    ],
    "originating_ip": "192.0.2.1",
    "categories": null,
    "unique_args": null,
    "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
}

Filter all messages [GET]

Email Activityのログを取得します。検索条件を指定してログを絞り込むこともできます。

検索条件を指定するクエリはURLエンコードする必要があります。URLエンコードはこちらのツールで行えます。

「Hello, SendGrid!」という件名のメールを検索する場合、

subject="Hello, SendGrid!"

をURLエンコードした以下の文字列をqueryパラメータに指定してください。

query=subject%3D%22Hello%2C%20SendGrid!%22

使用可能なクエリタイプの一覧はこちらをご確認ください。

URI引数	必須	条件	説明
query	No	string	検索条件
limit	Yes	integer	取得する結果の件数上限（1~1000の整数）

Request

GET https://api.sendgrid.com/v3/messages?query={url_encoded_query}&limit=1 HTTP/1.1

Response

JSONパラメータ	型	制限
messages	オブジェクト配列

from_email	string	メールアドレス
	送信元メールアドレス
msg_id	string
	メッセージID（SendGrid Message ID）
subject	string
	メールの件名
to_email	string	メールアドレス
	宛先メールアドレス
status	string	processing, delivered, not_delivered のいずれか
	メールの送信状況
opens_count	integer
	メールが開封された回数
clicks_count	integer
	リンクがクリックされた回数
last_event_time	string	ISO 8601フォーマット（YYYY-MM-DDThh:mm:ss）
	最後にイベントが発生した日時

HTTP/1.1 200
{
    "messages": [
        {
            "from_email": "from@example.com",
            "msg_id": "s5wf5dtoQq65RXku92Qo9Q.filterdrecv-6b67f67d45-5tl7b-1-6641E9C0-8.0",
            "subject": "Hello, SendGrid!",
            "to_email": "to@example.com",
            "status": "delivered",
            "opens_count": 0,
            "clicks_count": 0,
            "last_event_time": "2024-05-13T10:21:55Z"
        }
    ]
}

Request a CSV [POST]

Email ActivityのログをCSVファイルとして生成します。生成が完了するとファイルをダウンロードするためのメールがアカウントのメールアドレス宛に送信されます。ダウンロード用リンクの有効期限は3日間です。
抽出条件を指定すればCSVファイルに含めるデータを絞り込むことができます。

URI引数	必須	条件	説明
query	No	string	抽出条件

Request

POST https://api.sendgrid.com/v3/messages/download HTTP/1.1

例えばOpenイベントが発生したメールのみを抽出する場合、検索条件「Contains(events,”open”)」をエンコードした文字列をqueryに指定して以下のようにリクエストしてください。

POST https://api.sendgrid.com/v3/messages/download?query=Contains(events%2C%22open%22) HTTP/1.1

Response

JSONパラメータ	型	制限
status	string	常に“pending”が返される

message	string

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

download_uuidの取得

生成完了後にSendGridから届くメールの「Download」ボタンを押すと、ダッシュボードへの遷移と同時にCSVファイルのダウンロードが始まります。Download CSVエンドポイントで使用するdownload_uuidパラメータは、このときアクセスしている画面のURLから取得してください。

「Download」ボタンは必ずアカウントにログインした状態で押してください。ログインしていない場合、遷移先の画面でエラーメッセージが表示されます。

Download CSV [GET]

Request a CSVエンドポイントで生成したCSVファイルをダウンロードするための署名付きURLを取得します。取得したURLにアクセスすると、CSVファイルをダウンロードできます。

URI引数	必須	条件	説明
download_uuid	Yes	string	Request a CSVエンドポイントで取得したUUID

Request

GET https://api.sendgrid.com/v3/messages/download/{download_uuid} HTTP/1.1

Response

JSONパラメータ		型	制限	詳細
presigned_url		string	URL
		ダウンロード用の署名付きURL

HTTP/1.1 202
{"presigned_url":"https://sendgrid-rts-production-csv-downloads.s3.us-west-2.amazonaws.com/…"}

メニュー

Filter messages by message ID [GET]

Request

Response

Filter all messages [GET]

Request

Response

Request a CSV [POST]

Request

Response

download_uuidの取得

Download CSV [GET]

Request

Response