Get mail request

Available in Classic and VPC

Get the status and processing statistics of a single mail send request. Query with the requestId returned by the Create mail request API. Use this API to track the sending 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 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	Mail service ID NRN (NCP Resource Name) format (e.g., `ncp:mail:kr:1********2:main`) See Get project list.
`requestId`	String	Required	Send request ID Enter the value returned by Create mail request. See Get 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: en-US'

Response

This section describes the response format.

Response headers

The following describes the response headers.

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

Response body

The response body includes the following data:

Field	Type	Required	Description
`requestId`	String	-	Send request ID The internal structure of the value is not a fixed contract. Use the value as is without parsing it.
`status`	String	-	Send request status `PREPARING` \| `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` `PREPARING`: the send request has been accepted and is being prepared `READY`: preparation is complete and the request is waiting to start sending `RESERVED`: waiting for the reserved sending time `SENDING`: the mails in the request are being sent `COMPLETED`: all mails have been sent `FAILED`: all mails failed to be sent `PARTIAL_FAILED`: some mails failed to be sent `CANCELED`: the send request has been canceled
`createDateTime`	String	-	Date and time the send request was accepted ISO 8601 format
`requestCount`	Integer	-	Number of mails to send Group sending splits recipients into multiple mails, so this may differ from the number of recipients. For individual sending, it equals the number of recipients.
`readyCount`	Integer	-	Number of mails saved Total across all statuses
`sentCount`	Integer	-	Number of mails sent successfully
`finishCount`	Integer	-	Number of mails whose processing has finished Total of successes, failures, unsubscribed, and canceled
`reservationDateTime`	String	-	Reserved sending date and time ISO 8601 format `null` for immediate send requests
`countsByStatus`	Array	-	Number of mails by status: countsByStatus The total equals `requestCount`. Statuses with a count of 0 are not included.

`countsByStatus`

The following describes countsByStatus.

Field	Type	Required	Description
`status`	String	-	Sending status `READY` \| `RESERVED` \| `SENDING` \| `RETRYING` \| `COMPLETED` \| `FAILED` \| `ERRORED` \| `UNSUBSCRIBED` \| `BLOCKED` \| `CANCELED` `READY`: waiting to start sending `RESERVED`: waiting for the reserved sending time `SENDING`: attempting to deliver the mail to the recipient `RETRYING`: waiting for a retry scheduled after a temporary failure `COMPLETED`: the mail was delivered to the recipient successfully `FAILED`: sending failed, for example because the receiving server rejected the mail `ERRORED`: sending ended with an error during processing `UNSUBSCRIBED`: not sent because the address has unsubscribed `BLOCKED`: not sent because the address is on the send block list `CANCELED`: sending has been canceled
`count`	Integer	-	Number of mails in the status

Note

Until status reaches a final state, the response includes the retry-after header. Wait for the number of seconds in that header before querying again.
Recipients that were not sent to because of unsubscription or send blocking are not counted as successes. Check the specific cause of failures and errors with recipients[].sendResultCode of the Get mail 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 Simple & Easy Notification Service APIs, 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 below is returned.

Error response body

The response body when a call fails includes the following data:

Field	Type	Required	Description
`error`	Object	-	Error information
`error.errorCode`	String	-	Error code See the Code column of the response status code table.
`error.message`	String	-	Fixed message for each error code Returned in the language specified in the `x-ncp-lang` header
`error.detail`	String	-	Detailed reason for the request Omitted if there is no applicable reason
`error.fieldErrors`	Array	-	List of errors by parameter `field`: name of the parameter with the error `message`: reason for the error Omitted if the error is not a parameter error

Error response example

The response example when a call fails is as follows:

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