---
title: "Get email list"
slug: "sens-mail-list"
updated: 2026-10-08T04:15:12Z
published: 2026-10-08T04:15:12Z
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.

# Get email list

Available in Classic and VPC

Get the list of emails included in the delivery request. This API returns only the summary fields needed to browse the list. If you need results by body, attachment, or recipient, use the [Get email details](/docs/en/sens-mail-get) API.

## Request

This section describes the request format. The method and URI are as follows:

| Method | URI |
| --- | --- |
| GET | /mail/v2/services/{serviceId}/requests/{requestId}/mails |

### Request headers

For information about the request headers common to all Simple & Easy Notification Service APIs, see [Simple & Easy Notification Service request headers](/docs/en/sens-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94).

| Field | Required | Description |
| --- | --- | --- |
| `x-ncp-lang` | Optional | Response message language - `en-US` (default) \| `ko-KR` \| `ja-JP` |

### Request path parameters

You can use the following path parameters with your request:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `serviceId` | String | Required | Email service ID - NRN (NCP Resource Name) format (e.g., `ncp:mail:kr:1********2:main`). - See [Get project list](/docs/en/sens-project-list). |
| `requestId` | String | Required | Delivery request ID - Enter the value received in the response of [Create email delivery request](/docs/en/sens-mail-request-create). - See [Get delivery request list](/docs/en/sens-mail-request-list). |

### Request query parameters

You can use the following query parameters with your request:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mailId` | String | Optional | Email ID - Retrieves items that exactly match. |
| `recipientAddress` | String | Optional | Recipient email address - Retrieves items that exactly match. |
| `title` | String | Optional | Email subject - Searches partial matches. |
| `status` | String | Optional | Mail delivery status - `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` - You can specify this parameter multiple times. If multiple values are specified, they are treated with OR logic (e.g., `status=COMPLETED&status=FAILED`). - Comma-separated multiple values (`status=A,B`) are not supported. - For the meaning of each value, see the `mails[].status` field in the response. |
| `pageNo` | Integer | Optional | Page number - Starts from 0 (default: 0). |
| `pageSize` | Integer | Optional | Number of items per page - 1-1000 (default: 10) |
| `sort` | String | Optional | Sort criteria - `{field},{direction}` format (e.g., `createDateTime,desc`). - Available fields: `mailId` \| `createDateTime` \| `status` - Direction: `asc` (default) \| `desc` - If not specified, sorted by `createDateTime,desc`. |

              Note

              

- If multiple filters are specified together, they are applied with AND logic.
- For authorized callers only, if the `requestId` in the path does not exist, a `404` is returned. This is different from there being no emails that match the criteria (empty array + `200`).
- If sort keys are not unique, the order of entries with the same value is not guaranteed.

### Request example

The request example is as follows:

```
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'
```

## Response

This section describes the response format.

### Response body

The response body includes the following data:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mails` | Array | - | Email list: [mails](/docs/en/sens-mail-list#mails) - If there are no items matching the criteria, an empty array is returned. |
| `totalElements` | Integer | - | Total number of items that meet the criteria |
| `totalPages` | Integer | - | Total number of pages |
| `pageNo` | Integer | - | Current page number |
| `pageSize` | Integer | - | Number of items per page |

#### `mails`

The following describes `mails`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `requestId` | String | - | Delivery request ID |
| `mailId` | String | - | Email ID - Used as the path parameter for the [Get email details](/docs/en/sens-mail-get) API. |
| `createDateTime` | String | - | Delivery request acceptance date and time - ISO 8601 format |
| `title` | String | - | Email subject |
| `templateNo` | Integer | - | Template number used - `null` for deliveries that didn't use a template. |
| `templateName` | String | - | Template name used - `null` for deliveries that didn't use a template. |
| `status` | String | - | Email delivery status - `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` - `READY`: Waiting for delivery to begin. - `RESERVED`: Waiting for the scheduled delivery time. - `SENDING`: Sending the email. - `COMPLETED`: Delivery completed to all recipients of the email. - `FAILED`: Delivery failed to all recipients associated with the email. - `PARTIAL_FAILED`: Delivery failed to only some of the recipients associated with the email. - `CANCELED`: Delivery canceled. |
| `senderAddress` | String | - | Sender email address |
| `senderName` | String | - | Sender name - `null` for deliveries with no entry. |
| `sendDateTime` | String | - | Delivery completion date and time - ISO 8601 format. - `null` for emails whose delivery hasn't started. |
| `representativeRecipient` | String | - | Primary recipient email address - If there are multiple recipients, the address of one of them. - View the full list using the [Get email details](/docs/en/sens-mail-get) API. |
| `recipientCount` | Integer | - | Number of recipients - Includes `CC` and `BCC` recipients. |
| `sendType` | String | - | Delivery type - `IMMEDIATE` \| `RESERVED` - `IMMEDIATE`: Immediate delivery. - `RESERVED`: Scheduled delivery. |
| `advertising` | Boolean | - | Whether it is an ad email - `true` \| `false` |

              Note

              

Recipients whose emails were not delivered due to unsubscription (`UNSUBSCRIBED`), blocking (`BLOCKED`), or processing errors (`ERRORED`) are not counted as successes; therefore, emails containing only such recipients are reported as `FAILED`. To view the reasons for each recipient, check `recipients[].status` and `recipients[].sendResultCode` of the [Get email details](/docs/en/sens-mail-get) API.

### Response status codes

The following describes the response status codes:

| HTTP status code | Code | Message | Description |
| --- | --- | --- | --- |
| 200 | - | OK | Request succeeded |
| 400 | InvalidParameter | Bad Request | Request parameter error |
| 401 | Unauthorized | Unauthorized | Authentication failed |
| 403 | Forbidden | Forbidden | No permission for the `serviceId` in the path. |
| 404 | NotFound | Not Found | The `requestId` in the path does not exist. |
| 500 | InternalServerError | Internal Server Error | Internal server error |

              Note

              

Unlike other APIs in the Simple & Easy Notification Service, the Mail v2 API returns errors in the NCP API standard error format. Instead of the `status` and `error` (string) fields in the response body, the `error` object shown below is returned.

#### Error response body

The response body includes the following data if the call fails.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | Object | - | Error information |
| `error.errorCode` | String | - | Error code - See the code column in the response status code table. |
| `error.message` | String | - | Predefined message for each error code - Returned in the language specified in the `x-ncp-lang` header. |
| `error.detail` | String | - | Detailed reason for each request - This field is omitted if there is no applicable reason. |
| `error.fieldErrors` | Array | - | List of errors by parameter - `field`: Name of the parameter where the error occurred. - `message`: Reason for the error. - If the error is not parameter-related, this field is omitted. |

#### Error response example

The following is a sample response upon a failed call.

```
{
"error": {
"errorCode": "NotFound",
"message": "The requested resource was not found."
}
}
```

### Response example

The response example is as follows:

```
{
"mails": [
{
"requestId": "20260712-R-01K0ZQ8YV3M4N5P6R7S8T9VAWX-777",
"mailId": "20260712-M-01K0ZQ8YVBQ7C2D3E4F5G6H7J8-777",
"createDateTime": "2026-07-12T15:19:53+09:00",
"title": "Welcome, Gildong Hong.",
"templateNo": 41,
"templateName": "Membership level change notice",
"status": "PARTIAL_FAILED",
"senderAddress": "no_reply@company.com",
"senderName": "Customer center",
"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
}
```