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 API, and if you need individual mails, use the Get email 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.

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.

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 `±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 `±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&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 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 and Get email 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 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
}