---
title: "Get delivery request"
slug: "sens-mail-request-get"
updated: 2026-10-08T04:14:36Z
published: 2026-10-08T04:14:36Z
canonical: "api.ncloud-docs.com/sens-mail-request-get"
---

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

Available in Classic and VPC

This API retrieves the status and processing statistics for a single email delivery request. It uses the `requestId` returned by the [Create email delivery request](/docs/en/sens-mail-request-create) API and is used to track the delivery progress.

## Request

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

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

### 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 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' \
--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 headers

The following describes the response headers.

| Field | Required | Description |
| --- | --- | --- |
| `retry-after` | - | Time to wait until the next poll (second) - Returned only until the `status` reaches a completed state (`COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED`). - Not returned once a completed state is reached. |

### Response body

The response body includes the following data:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `requestId` | String | - | Delivery request ID - Since the internal structure of the value is not fixed by contract, do not parse it; use it as is. |
| `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. |
| `createDateTime` | String | - | Delivery request acceptance date and time - ISO 8601 format |
| `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 the number of recipients. |
| `readyCount` | Integer | - | Number of emails saved - Total across all statuses |
| `sentCount` | Integer | - | Number of emails successfully sent |
| `finishCount` | Integer | - | Number of emails whose processing has been completed - Total of success, failure, bounce, and cancellation |
| `reservationDateTime` | String | - | Scheduled delivery date and time - ISO 8601 format. - `null` for immediate delivery requests. |
| `countsByStatus` | Array | - | Distribution of counts by email status: [countsByStatus](/docs/en/sens-mail-request-get#countsbystatus) - The total count is the same as `requestCount` - Statuses with a count of 0 are not included. |

#### `countsByStatus`

The following describes `countsByStatus`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | String | - | Delivery status - `READY` \| `RESERVED` \| `SENDING` \| `RETRYING` \| `COMPLETED` \| `FAILED` \| `ERRORED` \| `UNSUBSCRIBED` \| `BLOCKED` \| `CANCELED` - `READY`: Waiting for delivery to begin. - `RESERVED`: Waiting for the scheduled delivery time. - `SENDING`: Attempting to send the email to the recipient. - `RETRYING`: Waiting for a retry scheduled due to a temporary failure. - `COMPLETED`: The email was successfully sent to the recipient. - `FAILED`: Delivery failed due to a rejection by the receiving server, etc. - `ERRORED`: Terminated due to an error during delivery processing. - `UNSUBSCRIBED`: The email was not sent because the address is on the opted-out list. - `BLOCKED`: The email was not sent because the address is on the block list. - `CANCELED`: Delivery canceled. |
| `count` | Integer | - | Number of emails with this status |

              Note

              

- The `retry-after` header is included in the response until `status` reaches the completed state. Wait for the specified number of seconds and then try the query again.
- Recipients whose messages were not delivered due to opt-out or blocking are not counted as successful. Check the `recipients[].sendResultCode` of [Get email details](/docs/en/sens-mail-get) API to determine the specific cause of the failure.

### 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:

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