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

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.
`requestId`	String	Required	Delivery request ID Enter the value received in the response of Create email delivery request. See Get delivery 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 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 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
}
]
}