送信リクエストリストの照会

       <p class="platform-info type-classic-vpc">Classic/VPC環境で利用できます。</p>

サービスのメール送信リクエストリストを照会します。リストの探索に必要な要約フィールドのみ返されます。処理統計が必要な場合は、送信リクエストの照会 APIを、個別メールが必要な場合は、メールリストの照会 APIを使用してください。

リクエスト

リクエスト形式を説明します。リクエスト形式は次の通りです。

メソッド	URI
GET	/mail/v2/services/{serviceId}/requests

リクエストヘッダ

Simple & Easy Notification Service APIで共通して使用されるヘッダの詳細は、Simple & Easy Notification Serviceのリクエストヘッダをご参照ください。

フィールド	必須の有無	説明
`x-ncp-lang`	Optional	レスポンスメッセージの言語 `en-US` (デフォルト)\| `ko-KR` \| `ja-JP`

リクエストパスパラメータ

リクエストパスパラメータの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`serviceId`	String	Required	メールサービス ID NRN(NAVERクラウドプラットフォーム Resource Name)形式 (例: `ncp:mail:kr:1********2:main`) プロジェクトリストの照会を参照

リクエストクエリパラメータ

リクエストクエリパラメータの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`fromDateTime`	String	Required	照会期間の開始日時送信リクエスト受付日時基準 ISO 8601形式、タイムゾーンオフセット(`Z`または`±hh:mm`)を含む (URLエンコードが必要)
`toDateTime`	String	Required	照会期間の終了日時送信リクエスト受付日時基準 ISO 8601形式、タイムゾーンオフセット(`Z`または`±hh:mm`)を含む (URLエンコードが必要)
`requestId`	String	Optional	送信リクエスト ID 完全一致する項目を照会
`mailId`	String	Optional	メール ID 当該メールを含む送信リクエストを照会
`title`	String	Optional	メール件名一部一致を検索
`templateNo`	Integer	Optional	テンプレート番号完全一致する項目を照会
`senderAddress`	String	Optional	送信者メールアドレス完全一致する項目を照会
`recipientAddress`	String	Optional	受信者のメールアドレス完全一致する項目を照会
`dispatchType`	String	Optional	送信経路 `CONSOLE` \| `API` `CONSOLE`: コンソールから送信 `API`: API経由で送信
`status`	String	Optional	送信リクエストの状態 `PREPARING` \| `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` 複数回指定が可能で、複数の値を指定した場合は OR条件として動作 (例: `status=COMPLETED&status=FAILED`) コンマで区切った複数値(`status=A,B`)は対応しない値の意味はレスポンスの`requests[].status`を参照
`pageNo`	Integer	Optional	ページ番号 0からスタート (デフォルト: 0)
`pageSize`	Integer	Optional	ページごとの項目数 1~1000 (デフォルト: 10)
`sort`	String	Optional	ソート条件 `{フィールド},{方向}`形式(例: `createDateTime,desc`) ソート可能なフィールド: `createDateTime` \| `recipientCount` \| `reservationDateTime` \| `sendDateTime` \| `status` 方向: `asc`(デフォルト)\| `desc` 未指定の場合は`createDateTime,desc`でソート

参考

タイムゾーンオフセットの+ は、クエリ文字列で%2Bにエンコードします。(例: fromDateTime=2026-07-01T00:00:00%2B09:00)
異なるフィルタを組み合わせて指定した場合は AND として動作します。
ソートキーが一意でない場合、同一値の項目間の順序は保証されません。

リクエスト例

リクエストのサンプルコードは次の通りです。

curl --location --request GET 'https://sens.apigw.ntruss.com/mail/v2/services/ncp:mail:kr:1********2:main/requests?fromDateTime=2026-07-01T00%3A00%3A00%2B09%3A00&toDateTime=2026-07-12T23%3A59%3A59%2B09%3A00&status=COMPLETED&pageNo=0&pageSize=10&sort=createDateTime%2Cdesc' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'x-ncp-lang: ko-KR'

レスポンス

レスポンス形式を説明します。

レスポンスボディ

レスポンスボディの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`requests`	Array	-	送信リクエストリスト: requests 条件に合致する項目がない場合は空の配列
`totalElements`	Integer	-	条件に合致する項目の総数
`totalPages`	Integer	-	ページの総数
`pageNo`	Integer	-	現在のページ番号
`pageSize`	Integer	-	ページごとの項目数

`requests`

requestsの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`requestId`	String	-	送信リクエスト ID 送信リクエストの照会、メールリストの照会 APIのパスパラメータとして使用
`createDateTime`	String	-	送信リクエストの受付日時 ISO 8601形式
`templateNo`	Integer	-	使用されたテンプレート番号テンプレートを使用していない送信の場合は`null`
`templateName`	String	-	使用されたテンプレートの名前テンプレートを使用していない送信の場合は`null`
`status`	String	-	送信リクエスト状態 `PREPARING` \| `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` `PREPARING`: 送信リクエストを受付して準備中 `READY`: 送信準備が完了し、送信開始を待機中 `RESERVED`: 予約された送信時刻を待機中 `SENDING`: リクエストに含まれたメールを送信中 `COMPLETED`: すべてのメールの送信が完了 `FAILED`: すべてのメールの送信が失敗 `PARTIAL_FAILED`: 一部のメールの送信が失敗 `CANCELED`: 送信リクエストがキャンセルされた
`senderAddress`	String	-	送信者のメールアドレス
`senderName`	String	-	送信者の名前入力していない送信の場合は`null`
`dispatchType`	String	-	送信経路 `CONSOLE` \| `API` `CONSOLE`: コンソールから送信 `API`: API経由で送信
`elapsedTime`	String	-	送信所要時間 `HH:mm:ss.SSS`形式 (24時間を超えると時間の桁数が増える) 送信が完了していないリクエストは`null`
`sendDateTime`	String	-	送信完了日時 ISO 8601形式送信が開始されていないリクエストは`null`
`reservationDateTime`	String	-	予約送信日時 ISO 8601形式即時送信リクエストは`null`
`requestCount`	Integer	-	送信メール件数一般送信は受信者を分割して複数通作成するため、受信者数と異なる場合がある個別送信の場合は`recipientCount`と同じ
`recipientCount`	Integer	-	受信者数 `CC`、`BCC`受信者を含む一般送信の場合、`requestCount`以上

参考

受信拒否や送信ブロックにより送信されなかった受信者は成功としてカウントされません。そのため、受信拒否アドレスのみが含まれるリクエストはFAILEDと判定されます。受信者ごとの理由はメールの詳細照会 APIのrecipients[]でご確認ください。

レスポンスステータスコード

レスポンスステータスコードの説明は次の通りです。

HTTPステータスコード	コード	メッセージ	説明
200	-	OK	リクエスト成功
400	InvalidParameter	Bad Request	リクエストパラメータエラー `fromDateTime`、`toDateTime`の欠落または形式エラーを含む
401	Unauthorized	Unauthorized	認証失敗
403	Forbidden	Forbidden	パス内の`serviceId`に対する権限なし
404	NotFound	Not Found	パスのリソースが存在しない
500	InternalServerError	Internal Server Error	サーバ内部エラー

参考

Simple & Easy Notification Serviceの他の APIと異なり、メール v2 APIは NAVERクラウドプラットフォーム API標準エラー形式でエラーを返します。レスポンスボディのstatus、error(文字列)フィールドではなく、以下のerrorオブジェクトが返されます。

エラーレスポンスボディ

呼び出しが失敗した場合のレスポンスボディの説明は次の通りです。

フィールド	タイプ	必須の有無	説明
`error`	Object	-	エラー情報
`error.errorCode`	String	-	エラーコードレスポンスステータスコード表のコード列を参照
`error.message`	String	-	エラーコードごとの固定メッセージ `x-ncp-lang`ヘッダに指定した言語で返す
`error.detail`	String	-	リクエストごとの詳細理由該当する理由がない場合はフィールドが省略される
`error.fieldErrors`	Array	-	パラメータ別エラーリスト `field`: エラーが発生したパラメータの名前 `message`: エラーの理由パラメータエラーでない場合はフィールドは省略される

エラーレスポンス例

呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。

{
"error": {
"errorCode": "InvalidParameter",
"message": "The request contains an invalid parameter."
}
}

レスポンス例

レスポンスのサンプルコードは次の通りです。

{
"requests": [
{
"requestId": "20260712-R-01K0ZQ8YV3M4N5P6R7S8T9VAWX-777",
"createDateTime": "2026-07-12T09:59:35+09:00",
"templateNo": null,
"templateName": null,
"status": "COMPLETED",
"senderAddress": "no_reply@company.com",
"senderName": null,
"dispatchType": "API",
"elapsedTime": "00:00:05.230",
"sendDateTime": "2026-07-12T09:59:40+09:00",
"reservationDateTime": null,
"requestCount": 4,
"recipientCount": 100
}
],
"totalElements": 21,
"totalPages": 3,
"pageNo": 0,
"pageSize": 10
}