Email Activity API

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

  1. 指定したメッセージIDに該当するEmail Activityのログを取得する
  2. 検索条件を指定して、該当するEmail Activityのログを取得する
  3. Email ActivityのログをCSVファイルとして生成する
  4. 生成したCSVファイルをダウンロードする

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

Filter messages by message ID [GET]

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

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

Request

1

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アドレス）		 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

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!」という件名のメールを検索する場合、

1

subject="Hello, SendGrid!"

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

1

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

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

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

Request

1

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 ISO8601フォーマット（YYYY-MM-DDThh:mm:ss）
最後にイベントが発生した日時 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

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

1

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

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

1

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

Response

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

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

1

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

Response

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

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