メールリストの照会

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

送信リクエストに含まれるメールリストを照会します。リスト閲覧に必要な要約フィールドのみを返します。本文・添付ファイル・受信者ごとの結果が必要な場合はメール詳細の照会 APIをご利用ください。

リクエスト

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

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

リクエストヘッダ

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

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

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

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

フィールド	タイプ	必須の有無	説明
`serviceId`	String	Required	メールサービス ID NRN(NCP Resource Name)形式(例: `ncp:mail:kr:1********2:main`) プロジェクトリストの照会を参照
`requestId`	String	Required	送信リクエスト ID メール送信リクエストの作成時にレスポンスで受け取った値を入力送信リクエストリストの照会を参照

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

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

フィールド	タイプ	必須の有無	説明
`mailId`	String	Optional	メール ID 完全一致する項目を照会
`recipientAddress`	String	Optional	受信者のメールアドレス完全一致する項目を照会
`title`	String	Optional	メールの件名部分一致検索
`status`	String	Optional	メールの送信状態 `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` 繰り返し指定が可能で、複数の値を指定すると ORで動作(例: `status=COMPLETED&status=FAILED`) カンマ区切りの複数値(`status=A,B`)は未対応値の意味はレスポンスの`mails[].status`を参照
`pageNo`	Integer	Optional	ページ番号 0から開始(デフォルト: 0)
`pageSize`	Integer	Optional	ページあたりの項目数 1~1000(デフォルト: 10)
`sort`	String	Optional	ソート条件 `{フィールド},{方向}`形式(例: `createDateTime,desc`) ソート可能なフィールド: `mailId` \| `createDateTime` \| `status` 方向: `asc` (デフォルト) \| `desc` 未指定の場合は`createDateTime,desc`でソート

参考

異なるフィルタを一緒に指定すると ANDで動作します。
権限のある呼び出し元に限り、パスのrequestIdが存在しない場合は404を返します。条件に一致するメールがない場合(空の配列 + 200)とは異なります。
ソートキーが一意でない場合、同じ値の項目間の順序は保証されません。

リクエスト例

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

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

レスポンス

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

レスポンスボディ

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

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

`mails`

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

フィールド	タイプ	必須の有無	説明
`requestId`	String	-	送信リクエスト ID
`mailId`	String	-	メール ID メール詳細の照会 APIのパスパラメータとして使用
`createDateTime`	String	-	送信リクエストの受付日時 ISO 8601形式
`title`	String	-	メールの件名
`templateNo`	Integer	-	使用したテンプレート番号テンプレートを使用しない送信は`null`
`templateName`	String	-	使用したテンプレート名テンプレートを使用しない送信は`null`
`status`	String	-	メールの送信状態 `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` `READY`: 送信開始を待機中 `RESERVED`: 予約した送信時刻を待機中 `SENDING`: メールを送信中 `COMPLETED`: メールに含まれるすべての受信者への送信が完了 `FAILED`: メールに含まれるすべての受信者への送信が失敗 `PARTIAL_FAILED`: メールに含まれる受信者の一部への送信が失敗 `CANCELED`: 送信がキャンセルされた
`senderAddress`	String	-	送信者のメールアドレス
`senderName`	String	-	送信者名入力しない送信は`null`
`sendDateTime`	String	-	送信完了日時 ISO 8601形式送信が開始されていないメールは`null`
`representativeRecipient`	String	-	代表受信者のメールアドレス受信者が複数の場合はそのうち1人のアドレス全リストはメール詳細の照会 APIで確認
`recipientCount`	Integer	-	受信者数 `CC`、`BCC`の受信者を含む
`sendType`	String	-	送信タイプ `IMMEDIATE` \| `RESERVED` `IMMEDIATE`: 即時送信 `RESERVED`: 予約送信
`advertising`	Boolean	-	広告メールの有無 `true` \| `false`

参考

受信拒否(UNSUBSCRIBED)・送信ブロック(BLOCKED)・処理エラー(ERRORED)により送信されなかった受信者は成功として集計されないため、該当受信者のみのメールはFAILEDと表示されます。受信者ごとの理由はメール詳細の照会 APIのrecipients[].statusと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は NCP 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."
}
}

レスポンス例

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

{
"mails": [
{
"requestId": "20260712-R-01K0ZQ8YV3M4N5P6R7S8T9VAWX-777",
"mailId": "20260712-M-01K0ZQ8YVBQ7C2D3E4F5G6H7J8-777",
"createDateTime": "2026-07-12T15:19:53+09:00",
"title": "山田太郎様、ようこそ。",
"templateNo": 41,
"templateName": "会員ランク変更のご案内",
"status": "PARTIAL_FAILED",
"senderAddress": "no_reply@company.com",
"senderName": "カスタマーセンター",
"sendDateTime": "2026-07-12T15:19:53+09:00",
"representativeRecipient": "yamada@example.com",
"recipientCount": 30,
"sendType": "IMMEDIATE",
"advertising": false
}
],
"totalElements": 2,
"totalPages": 1,
"pageNo": 0,
"pageSize": 10
}