Get mail list

Available in Classic and VPC

Get the list of mails included in a send request. Only the summary fields needed to browse the list are returned. Use the Get mail API for the body, attachments, and per-recipient results.

Request

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

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

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 query parameters

You can use the following query parameters with your request:

Field	Type	Required	Description
`mailId`	String	Optional	Mail ID Returns exact matches
`recipientAddress`	String	Optional	Recipient email address Returns exact matches
`title`	String	Optional	Mail subject Partial match search
`status`	String	Optional	Mail sending status `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 `mails[].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: `mailId` \| `createDateTime` \| `status` Direction: `asc` (default) \| `desc` If not specified, sorted by `createDateTime,desc`

Note

If different filters are specified together, they are combined with AND.
For callers with permission, 404 is returned if the requestId in the path does not exist. This is different from the case where no mail matches the conditions (an empty array with 200).
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/20260712-R-01K0ZQ8YV3M4N5P6R7S8T9VAWX-777/mails?status=PARTIAL_FAILED&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
`mails`	Array	-	Mail list: mails 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

`mails`

The following describes mails.

Field	Type	Required	Description
`requestId`	String	-	Send request ID
`mailId`	String	-	Mail ID Used as the path parameter of the Get mail API
`createDateTime`	String	-	Date and time the send request was accepted ISO 8601 format
`title`	String	-	Mail subject
`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	-	Mail sending status `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` `READY`: waiting to start sending `RESERVED`: waiting for the reserved sending time `SENDING`: the mail is being sent `COMPLETED`: the mail was sent to all of its recipients `FAILED`: the mail failed to be sent to all of its recipients `PARTIAL_FAILED`: the mail failed to be sent to some of its recipients `CANCELED`: sending has been canceled
`senderAddress`	String	-	Sender email address
`senderName`	String	-	Sender name `null` if not entered
`sendDateTime`	String	-	Date and time sending was completed ISO 8601 format `null` if sending has not started
`representativeRecipient`	String	-	Representative recipient email address If there are multiple recipients, the address of one of them Check the full list with the Get mail API.
`recipientCount`	Integer	-	Number of recipients Includes `CC` and `BCC` recipients
`sendType`	String	-	Sending type `IMMEDIATE` \| `RESERVED` `IMMEDIATE`: immediate sending `RESERVED`: reserved sending
`advertising`	Boolean	-	Whether the mail is an advertisement `true` \| `false`

Note

Recipients that were not sent to because of unsubscription (UNSUBSCRIBED), send blocking (BLOCKED), or a processing error (ERRORED) are not counted as successes, so a mail whose only recipients are such addresses is observed as FAILED. Check the reason for each recipient with recipients[].status and 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:

{
"mails": [
{
"requestId": "20260712-R-01K0ZQ8YV3M4N5P6R7S8T9VAWX-777",
"mailId": "20260712-M-01K0ZQ8YVBQ7C2D3E4F5G6H7J8-777",
"createDateTime": "2026-07-12T15:19:53+09:00",
"title": "Welcome, Hong Gildong.",
"templateNo": 41,
"templateName": "Membership level change notice",
"status": "PARTIAL_FAILED",
"senderAddress": "no_reply@company.com",
"senderName": "Customer Center",
"sendDateTime": "2026-07-12T15:19:53+09:00",
"representativeRecipient": "hongildong@example.com",
"recipientCount": 30,
"sendType": "IMMEDIATE",
"advertising": false
}
],
"totalElements": 2,
"totalPages": 1,
"pageNo": 0,
"pageSize": 10
}