送信リクエストの照会

Classic/VPC環境で利用できます。

1件のメール送信リクエストの状態と処理統計を照会します。メール送信リクエストの作成 APIが返したrequestIdで照会し、送信の進行状況の追跡に使用します。

リクエスト

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

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

リクエストヘッダ

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`) プロジェクトリストの照会を参照
`requestId`	String	Required	送信リクエスト ID メール送信リクエストの作成時にレスポンスとして受け取った値を入力送信リクエストリストの照会を参照

リクエスト例

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

curl --location --request GET 'https://sens.apigw.ntruss.com/mail/v2/services/ncp:mail:kr:1********2:main/requests/20260712-R-01K0ZQ8YV3M4N5P6R7S8T9VAWX-777' \
--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'

レスポンス

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

レスポンスヘッダ

レスポンスヘッダの説明は次の通りです。

フィールド	必須の有無	説明
`retry-after`	-	次回ポーリングまでの待機時間(秒) `status`が終了状態(`COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED`)に達する前までのみ返す終了状態に達すると返されない

レスポンスボディ

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

フィールド	タイプ	必須の有無	説明
`requestId`	String	-	送信リクエスト ID 値の内部構成は固定された契約ではないため、パースせずにそのまま使用
`status`	String	-	送信リクエスト状態 `PREPARING` \| `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` `PREPARING`: 送信リクエストを受付して準備中 `READY`: 送信準備が完了し、送信開始を待機中 `RESERVED`: 予約された送信時刻を待機中 `SENDING`: リクエストに含まれたメールを送信中 `COMPLETED`: すべてのメールの送信が完了 `FAILED`: すべてのメールの送信が失敗 `PARTIAL_FAILED`: 一部のメールの送信が失敗 `CANCELED`: 送信リクエストがキャンセルされた
`createDateTime`	String	-	送信リクエストの受付日時 ISO 8601形式
`requestCount`	Integer	-	送信メール件数一般送信の場合、受信者を分割して複数のメールを作成するため、受信者数と異なる場合がある個別送信の場合は受信者数と同じ
`readyCount`	Integer	-	保存が完了したメール件数全状態の合計
`sentCount`	Integer	-	送信成功メール件数
`finishCount`	Integer	-	処理終了メール件数成功・失敗・受信拒否・キャンセルの合計
`reservationDateTime`	String	-	予約送信日時 ISO 8601形式即時送信リクエストは`null`
`countsByStatus`	Array	-	メール別の件数分布: countsByStatus 件数の合計は`requestCount`と同じ件数が0の場合は含まれない

`countsByStatus`

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

フィールド	タイプ	必須の有無	説明
`status`	String	-	送信状態 `READY` \| `RESERVED` \| `SENDING` \| `RETRYING` \| `COMPLETED` \| `FAILED` \| `ERRORED` \| `UNSUBSCRIBED` \| `BLOCKED` \| `CANCELED` `READY`: 送信開始を待機中 `RESERVED`: 予約した送信時刻を待機中 `SENDING`: 受信者へのメール送信を試行中 `RETRYING`: 一時的な失敗により再試行が予約され待機中 `COMPLETED`: 受信者へのメールが正常に送信完了 `FAILED`: 受信サーバの拒否などにより送信失敗 `ERRORED`: 送信処理中のエラーにより終了 `UNSUBSCRIBED`: 受信拒否アドレスのため未送信 `BLOCKED`: 送信ブロックアドレスのため未送信 `CANCELED`: 送信がキャンセルされる
`count`	Integer	-	この状態のメール数

参考

statusが終了状態に達するまで、レスポンスにretry-afterヘッダが含まれます。その値(秒)だｋ待ってから、再度照会してください。
受信拒否や送信ブロックにより送信されなかった受信者は成功としてカウントされません。失敗やエラーの具体的な原因は、メールの詳細照会 APIのrecipients[].sendResultCodeでご確認ください。

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

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

HTTPステータスコード	コード	メッセージ	説明
200	-	OK	リクエスト成功
400	InvalidParameter	Bad Request	リクエストパラメータエラー
401	Unauthorized	Unauthorized	認証失敗
403	Forbidden	Forbidden	パス内の`serviceId`に対する権限なし
404	NotFound	Not Found	パス内の`requestId`が存在しない
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": "NotFound",
"message": "The requested resource was not found."
}
}

レスポンス例

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

{
"requestId": "20260712-R-01K0ZQ8YV3M4N5P6R7S8T9VAWX-777",
"status": "COMPLETED",
"createDateTime": "2026-07-12T10:00:00+09:00",
"requestCount": 35179,
"readyCount": 35179,
"sentCount": 33502,
"finishCount": 35179,
"reservationDateTime": null,
"countsByStatus": [
{
"status": "COMPLETED",
"count": 33502
},
{
"status": "FAILED",
"count": 1415
},
{
"status": "UNSUBSCRIBED",
"count": 262
}
]
}