---
title: "Get delivery request list"
slug: "sens-mail-request-list"
updated: 2026-10-08T04:14:34Z
published: 2026-10-08T04:14:34Z
canonical: "api.ncloud-docs.com/sens-mail-request-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 delivery request list

```
       <p class="platform-info type-classic-vpc">Available in Classic and VPC</p>
```

Get the list of email delivery requests for the service. This API returns only the summary fields needed to browse the list. If you need processing statistics, use the [Get delivery request](/docs/en/sens-mail-request-get) API, and if you need individual mails, use the [Get email list](/docs/en/sens-mail-list) API.

## Request

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

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

### 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). |

### Request query parameters

You can use the following query parameters with your request:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fromDateTime` | String | Required | Start date and time of the query period - Based on the time the delivery request was received. - ISO 8601 format, including timezone offset (`Z` or `&#xb1;hh:mm`) (URL encoding required). |
| `toDateTime` | String | Required | End date and time of the query period - Based on the time the delivery request was received. - ISO 8601 format, including time zone offset (`Z` or `&#xb1;hh:mm`) (URL encoding required). |
| `requestId` | String | Optional | Delivery request ID - Retrieves items that match exactly. |
| `mailId` | String | Optional | Email ID - Retrieves the delivery request containing the specified email. |
| `title` | String | Optional | Email subject - Searches partial matches. |
| `templateNo` | Integer | Optional | Template number - Retrieves items that match exactly. |
| `senderAddress` | String | Optional | Sender email address - Retrieves items that match exactly. |
| `recipientAddress` | String | Optional | Recipient email address - Retrieves items that exactly match. |
| `dispatchType` | String | Optional | Delivery path - `CONSOLE` \| `API` - `CONSOLE`: Sends from the console. - `API`: Sends via the API. |
| `status` | String | Optional | Delivery request status - `PREPARING` \| `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&amp;status=FAILED`). - Comma-separated multiple values (`status=A,B`) are not supported. - For the meaning of each value, see the `requests[].status` 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: `createDateTime` \| `recipientCount` \| `reservationDateTime` \| `sendDateTime` \| `status` - Direction: `asc` (default) \| `desc` - If not specified, sorted by `createDateTime,desc`. |

              Note

              

- The `+` in the time zone offset must be encoded as `%2B` in the query string. (E.g., `fromDateTime=2026-07-01T00:00:00%2B09:00`)
- If multiple filters are specified together, they are applied with AND logic.
- 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?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'
```

## Response

This section describes the response format.

### Response body

The response body includes the following data:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `requests` | Array | - | Delivery request list: [requests](/docs/en/sens-mail-request-list#requests) - An empty array if there are no items that match the criteria. |
| `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 |

#### `requests`

The following describes `requests`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `requestId` | String | - | Delivery request ID - Used as the path parameter for the [Get delivery request](/docs/en/sens-mail-request-get) and [Get email list](/docs/en/sens-mail-list) APIs. |
| `createDateTime` | String | - | Delivery request acceptance date and time - ISO 8601 format |
| `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 | - | Delivery request status - `PREPARING` \| `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` - `PREPARING`: The delivery request has been received and is being prepared. - `READY`: Preparation is complete and waiting for delivery to begin. - `RESERVED`: Waiting for the scheduled delivery time. - `SENDING`: Sending the emails included in the request. - `COMPLETED`: Delivery of all emails is complete. - `FAILED`: Failed to send all emails. - `PARTIAL_FAILED`: Failed to send some emails. - `CANCELED`: The delivery request was canceled. |
| `senderAddress` | String | - | Sender email address |
| `senderName` | String | - | Sender name - `null` for deliveries with no entry. |
| `dispatchType` | String | - | Delivery path - `CONSOLE` \| `API` - `CONSOLE`: Sends from the console. - `API`: Sends via the API. |
| `elapsedTime` | String | - | Time taken to send - `HH:mm:ss.SSS` format (if the time exceeds 24 hours, the number of digits in the hour field increases). - `null` for requests where delivery was not completed. |
| `sendDateTime` | String | - | Delivery completion date and time - ISO 8601 format. - `null` for requests where delivery has not started. |
| `reservationDateTime` | String | - | Scheduled delivery date and time - ISO 8601 format. - `null` for immediate delivery requests. |
| `requestCount` | Integer | - | Number of emails to be sent - For regular delivery, this may differ from the number of recipients because emails are split into multiple messages. - For individual delivery, this is equal to `recipientCount`. |
| `recipientCount` | Integer | - | Number of recipients - Includes `CC` and `BCC` recipients. - For regular delivery, this is greater than or equal to `requestCount`. |

              Note

              

Recipients whose messages were not delivered due to opt-out or blocking are not counted as successful. Therefore, requests containing only opt-out addresses are marked as `FAILED`. Check the `recipients[]` of the [Get email details](/docs/en/sens-mail-get) API for the reason for each recipient.

### 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 - `fromDateTime` and `toDateTime` missing or contains a format error. |
| 401 | Unauthorized | Unauthorized | Authentication failed |
| 403 | Forbidden | Forbidden | No permission for the `serviceId` in the path. |
| 404 | NotFound | Not Found | Resource does not exist at the path. |
| 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": "InvalidParameter",
"message": "The request contains an invalid parameter."
}
}
```

### Response example

The response example is as follows:

```
{
"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
}
```