Get email list

Available in Classic and VPC

Get the list of emails included in the delivery request. This API returns only the summary fields needed to browse the list. If you need results by body, attachment, or recipient, use the Get email details API.

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

You can use the following query parameters with your request:

Field	Type	Required	Description
`mailId`	String	Optional	Email ID Retrieves items that exactly match.
`recipientAddress`	String	Optional	Recipient email address Retrieves items that exactly match.
`title`	String	Optional	Email subject Searches partial matches.
`status`	String	Optional	Mail delivery status `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 `mails[].status` field 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: `mailId` \| `createDateTime` \| `status` Direction: `asc` (default) \| `desc` If not specified, sorted by `createDateTime,desc`.

Note

If multiple filters are specified together, they are applied with AND logic.
For authorized callers only, if the requestId in the path does not exist, a 404 is returned. This is different from there being no emails that match the criteria (empty array + 200).
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/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: ko-KR'

Response

This section describes the response format.

Response body

The response body includes the following data:

Field	Type	Required	Description
`mails`	Array	-	Email list: mails If there are no items matching the criteria, an empty array is returned.
`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

`mails`

The following describes mails.

Field	Type	Required	Description
`requestId`	String	-	Delivery request ID
`mailId`	String	-	Email ID Used as the path parameter for the Get email details API.
`createDateTime`	String	-	Delivery request acceptance date and time ISO 8601 format
`title`	String	-	Email subject
`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	-	Email delivery status `READY` \| `RESERVED` \| `SENDING` \| `COMPLETED` \| `FAILED` \| `PARTIAL_FAILED` \| `CANCELED` `READY`: Waiting for delivery to begin. `RESERVED`: Waiting for the scheduled delivery time. `SENDING`: Sending the email. `COMPLETED`: Delivery completed to all recipients of the email. `FAILED`: Delivery failed to all recipients associated with the email. `PARTIAL_FAILED`: Delivery failed to only some of the recipients associated with the email. `CANCELED`: Delivery canceled.
`senderAddress`	String	-	Sender email address
`senderName`	String	-	Sender name `null` for deliveries with no entry.
`sendDateTime`	String	-	Delivery completion date and time ISO 8601 format. `null` for emails whose delivery hasn't started.
`representativeRecipient`	String	-	Primary recipient email address If there are multiple recipients, the address of one of them. View the full list using the Get email details API.
`recipientCount`	Integer	-	Number of recipients Includes `CC` and `BCC` recipients.
`sendType`	String	-	Delivery type `IMMEDIATE` \| `RESERVED` `IMMEDIATE`: Immediate delivery. `RESERVED`: Scheduled delivery.
`advertising`	Boolean	-	Whether it is an ad email `true` \| `false`

Note

Recipients whose emails were not delivered due to unsubscription (UNSUBSCRIBED), blocking (BLOCKED), or processing errors (ERRORED) are not counted as successes; therefore, emails containing only such recipients are reported as FAILED. To view the reasons for each recipient, check recipients[].status and recipients[].sendResultCode of the Get email details 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 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:

{
"mails": [
{
"requestId": "20260712-R-01K0ZQ8YV3M4N5P6R7S8T9VAWX-777",
"mailId": "20260712-M-01K0ZQ8YVBQ7C2D3E4F5G6H7J8-777",
"createDateTime": "2026-07-12T15:19:53+09:00",
"title": "Welcome, Gildong Hong.",
"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
}