---
title: "メールリストの照会"
slug: "sens-mail-list"
updated: 2026-10-08T07:15:52Z
published: 2026-10-08T07:15:52Z
canonical: "api.ncloud-docs.com/sens-mail-list"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# メールリストの照会

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

送信リクエストに含まれるメールリストを照会します。リストの探索に必要な要約フィールドのみ返されます。本文・添付ファイル・受信者ごとの結果が必要な場合は、[メールの詳細照会](/docs/ja/sens-mail-get) APIを使用してください。

## リクエスト

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

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

### リクエストヘッダ

Simple & Easy Notification Service APIで共通して使用されるヘッダの詳細は、[Simple & Easy Notification Serviceのリクエストヘッダ](/docs/ja/sens-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)をご参照ください。

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

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

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

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `serviceId` | String | Required | メールサービス ID - NRN(NAVERクラウドプラットフォーム Resource Name)形式 (例: `ncp:mail:kr:1********2:main`) - [プロジェクトリストの照会](/docs/ja/sens-project-list)を参照 |
| `requestId` | String | Required | 送信リクエスト ID - [メール送信リクエストの作成](/docs/ja/sens-mail-request-create)時にレスポンスとして受け取った値を入力 - [送信リクエストリストの照会](/docs/ja/sens-mail-request-list)を参照 |

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

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

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `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: ko-KR'
```

## レスポンス

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

### レスポンスボディ

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

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `mails` | Array | - | メールリスト: [mails](/docs/ja/sens-mail-list#mails) - 条件に合致する項目が存在しない場合、空の配列 |
| `totalElements` | Integer | - | 条件に合致する項目の総数 |
| `totalPages` | Integer | - | ページの総数 |
| `pageNo` | Integer | - | 現在のページ番号 |
| `pageSize` | Integer | - | ページごとの項目数 |

#### `mails`

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

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `requestId` | String | - | 送信リクエスト ID |
| `mailId` | String | - | メール ID - [メールの詳細照会](/docs/ja/sens-mail-get) 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人のアドレス - 全リストは[メールの詳細照会](/docs/ja/sens-mail-get) APIで確認 |
| `recipientCount` | Integer | - | 受信者数 - `CC`、`BCC`受信者を含む |
| `sendType` | String | - | 送信タイプ - `IMMEDIATE` \| `RESERVED` - `IMMEDIATE`: 即時送信 - `RESERVED`: 予定送信 |
| `advertising` | Boolean | - | 広告メールかどうか - `true` \| `false` |

              参考

              

受信拒否(`UNSUBSCRIBED`)・送信ブロック(`BLOCKED`)・処理エラー(`ERRORED`)によって送信されなかった受信者は成功としてカウントされませんので、そのような受信者のみのメールは`FAILED`として扱われます。受信者ごとの理由は、[メールの詳細照会](/docs/ja/sens-mail-get) 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は 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."
}
}
```

### レスポンス例

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

```
{
"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": "hongildong@example.com",
"recipientCount": 30,
"sendType": "IMMEDIATE",
"advertising": false
}
],
"totalElements": 2,
"totalPages": 1,
"pageNo": 0,
"pageSize": 10
}
```