Get mail request list

Available in Classic and VPC

Get the list of mail send requests of a service. Only the summary fields needed to browse the list are returned. Use the Get mail request API for processing statistics, and the Get mail list API for individual mails.

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

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 date and time the send request was accepted ISO 8601 format including the time zone offset (`Z` or `±hh:mm`) (URL encoding required)
`toDateTime`	String	Required	End date and time of the query period Based on the date and time the send request was accepted ISO 8601 format including the time zone offset (`Z` or `±hh:mm`) (URL encoding required)
`requestId`	String	Optional	Send request ID Returns exact matches
`mailId`	String	Optional	Mail ID Returns the send request that contains the mail
`title`	String	Optional	Mail subject Partial match search
`templateNo`	Integer	Optional	Template number Returns exact matches
`senderAddress`	String	Optional	Sender email address Returns exact matches
`recipientAddress`	String	Optional	Recipient email address Returns exact matches
`dispatchType`	String	Optional	Sending channel `CONSOLE` \| `API` `CONSOLE`: sent from the console `API`: sent through the API
`status`	String	Optional	Send request status `PREPARING` \| `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` Can be repeated. Multiple values are combined with OR (e.g., `status=COMPLETED&status=FAILED`). Comma-separated multiple values (`status=A,B`) are not supported. For the meaning of each value, see `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 condition `{field},{direction}` format (e.g., `createDateTime,desc`) Sortable 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 different filters are specified together, they are combined with AND.
If the sort key is not unique, the order of items 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: en-US'

Response

This section describes the response format.

Response body

The response body includes the following data:

Field	Type	Required	Description
`requests`	Array	-	Send request list: requests An empty array if there are no matching items
`totalElements`	Integer	-	Total number of matching items
`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	-	Send request ID Used as the path parameter of the Get mail request and Get mail list APIs
`createDateTime`	String	-	Date and time the send request was accepted ISO 8601 format
`templateNo`	Integer	-	Number of the template used `null` if the mail was sent without a template
`templateName`	String	-	Name of the template used `null` if the mail was sent without a template
`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
`senderAddress`	String	-	Sender email address
`senderName`	String	-	Sender name `null` if not entered
`dispatchType`	String	-	Sending channel `CONSOLE` \| `API` `CONSOLE`: sent from the console `API`: sent through the API
`elapsedTime`	String	-	Time taken to send `HH:mm:ss.SSS` format (the hour part grows beyond two digits if it exceeds 24 hours) `null` if sending is not complete
`sendDateTime`	String	-	Date and time sending was completed ISO 8601 format `null` if sending has not started
`reservationDateTime`	String	-	Reserved sending date and time ISO 8601 format `null` for immediate sending
`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 `recipientCount`.
`recipientCount`	Integer	-	Number of recipients Includes `CC` and `BCC` recipients For group sending, it is greater than or equal to `requestCount`.

Note

Recipients that were not sent to because of unsubscription or send blocking are not counted as successes. Therefore, a request whose only recipients are unsubscribed addresses is judged as FAILED. Check the reason for each recipient with recipients[] 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 Includes cases where `fromDateTime` or `toDateTime` is missing or has an invalid format
401	Unauthorized	Unauthorized	Authentication failed
403	Forbidden	Forbidden	No permission for the `serviceId` in the path
404	NotFound	Not Found	The resource 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": "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
}