Create email delivery request

Available in Classic and VPC

Request an email delivery. Each delivery request is created as a single resource (requestId), and since delivery is handled asynchronously, this API returns only the receipt result.

Request

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

Method	URI
POST	/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 body

You can include the following data in the body of your request:

Field	Type	Required	Description
`senderAddress`	String	Conditional	Sender email address: Up to 254 bytes. Required if `templateNo` is not entered.
`senderName`	String	Optional	Sender name Up to 69 bytes (UTF-8).
`templateNo`	Integer	Conditional	Template number If entered, the sender, subject, and body stored in the template are used. If `senderAddress`, `title`, and `body`are entered together, the entered values will replace the template values. `senderAddress`, `title`, and `body` are required if this field is not entered.
`title`	String	Conditional	Email subject Up to 500 bytes (UTF-8). Placement variables in the format `${key}` are allowed. Required if `templateNo` is not entered.
`body`	String	Conditional	Email body Up to 500 KB (UTF-8; size is determined for each recipient after placeholder variables are substituted). For advertising emails (`advertising` is `true`), the size includes the opt-out text. HTML and `${key}` format placeholder variables can be used. Required if `templateNo` is not entered.
`individual`	Boolean	Optional	Whether to send individually `true` (default) \| `false` `true`: Emails are sent individually to each recipient, and other recipients’ addresses are not exposed. `false`: Emails are sent to multiple recipients in a single message, and recipients can see each other’s addresses. `true`: When set to `true`, `CC` and `BCC` recipients can't be used.
`confirmAndSend`	Boolean	Optional	Whether to send after confirmation `true` \| `false` (default) `true`: The message is received as ready-to-send and is sent after a separate confirmation process.
`advertising`	Boolean	Optional	Indicates whether the email is an advertisement. `true` \| `false` (default) `true`: An “Advertisement” label is added to the subject line, and an opt-out notice is included in the body. Can't be used for regular mailings where `individual` is set to `false`.
`parameters`	Object	Optional	Placeholders applied uniformly to all recipients `{"key": "value"}` format. `${key}` in the subject and body is replaced with the value. When entered, `recipients[].parameters` for individual recipients is not applied. If `${key}` appears in the subject or body, that key must exist in both the applicable scope (request-level or per-recipient); if the key is missing, the request is rejected.
`reservationDateTime`	String	Optional	Scheduled delivery date and time ISO 8601 format, including timezone offset (`Z` or `±hh:mm`) (e.g., `2026-07-10T09:00:00+09:00`) If not specified, immediate delivery is performed. Can be set for up to 30 days from the current time.
`attachFileIds`	Array	Optional	Lists attachment IDs. Maximum 10 MB per file, total maximum 20 MB.
`recipients`	Array	Conditional	Recipient list: recipients Up to 100,000 items allowed. At least one recipient of type `TO` is required. Required if `recipientGroupFilter` is not entered.
`recipientGroupFilter`	Object	Conditional	Specify recipients based on contacts groups: recipientGroupFilter Available only for individual deliveries whose `individual` is set to `true`. Required if `recipients` is not entered.
`useBasicUnsubscribeMessage`	Boolean	Optional	Whether to use the default opt-out message `true` (default) \| `false` `true`: Use the default opt-out message provided by the service. `false`: Use the message entered in `unsubscribeMessage`. The default opt-out message is approximately 900 bytes in size. Applies only to advertising emails (`advertising` is `true`).
`unsubscribeMessage`	String	Optional	Custom opt-out message Applies when `useBasicUnsubscribeMessage` is set to `false`. Applies the default opt-out message if left blank, even if `useBasicUnsubscribeMessage` is `false`. By default, it is appended after the `body`; to insert it within the body, enter the `#{UNSUBSCRIBE_MESSAGE}` tag at the desired location in `body`. The combined size of the `body` and opt-out message must not exceed 500 KB. Applies only to advertising emails (`advertising` is `true`); regular emails do not include an opt-out message.

Note

If you enter both recipients and recipientGroupFilter, the two lists will be concatenated for processing, and duplicates will not be removed even if the same address appears in both lists. In this case, two emails will be sent to that address, and two messages will be deducted from your monthly sending limit.
If you specify recipients using recipientGroupFilter, the 100,000-recipient limit does not apply; only the monthly sending limit applies.
Each of CC and BCC can have up to 30 recipients.
If the monthly sending limit is exceeded, a 429 ResourceQuotaExceeded error is returned.
The receipt response does not include the delivery status. Immediately after submission, the status is READY for immediate delivery or RESERVED for scheduled delivery; subsequent statuses can be checked by polling the Get delivery request API. The polling interval follows the retry-after response header of that API.

`recipients`

The following describes recipients.

Field	Type	Required	Description
`address`	String	Required	Recipient email address Up to 254 bytes.
`name`	String	Optional	Recipient name Up to 69 bytes (UTF-8).
`type`	String	Optional	Recipient type `TO` (default) \| `CC` \| `BCC` `TO`: Recipient. `CC`: Carbon copy (up to 30 people). `BCC`: Blind carbon copy (up to 30 people). If `individual` is `true`, `CC` and `BCC` cannot be used.
`parameters`	Object	Optional	Placeholder variable applicable only to the specified recipient `{"key": "value"}` format. Only applied if request-level `parameters` is not entered.

`recipientGroupFilter`

The following describes recipientGroupFilter.

Field	Type	Required	Description
`operator`	String	Optional	Group condition combination operator `OR` (default) \| `AND` `OR`: Recipients belonging to one or more of the specified groups. `AND`: Recipients belonging to all of the specified groups.
`groups`	Array	Required	Lists contacts group names.

Request example

The request example is as follows:

curl --location --request POST 'https://sens.apigw.ntruss.com/mail/v2/services/ncp:mail:kr:1********2:main/requests' \
--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' \
--header 'Content-Type: application/json' \
--data '{
"senderAddress": "no_reply@company.com",
"senderName": "Customer center",
"title": "Hello, ${customer_name}.",
"body": "Your grade has been changed from ${BEFORE_GRADE} to ${AFTER_GRADE}.",
"individual": true,
"advertising": false,
"recipients": [
{
"address": "hongildong@example.com",
"name": "Gildong Hong",
"type": "TO",
"parameters": {
"customer_name": "Gildong Hong",
"BEFORE_GRADE": "SILVER",
"AFTER_GRADE": "GOLD"
}
}
],
"useBasicUnsubscribeMessage": true
}'

Response

This section describes the response format.

Response body

The response body includes the following data:

Field	Type	Required	Description
`requestId`	String	-	Delivery request ID Used as a path parameter for the Get delivery request and Get email list APIs. The internal structure of the value is not fixed by contract, so do not parse it; use it as-is.
`requestCount`	Integer	-	Number of emails to be sent For regular delivery, multiple emails are created by splitting recipients, so this may differ from the number of recipients. For individual delivery (`individual`이 `true`), this is equal to the number of recipients.
`createDateTime`	String	-	Delivery request acceptance date and time ISO 8601 format

Response status codes

The following describes the response status codes:

HTTP status code	Code	Message	Description
202	-	Accepted	Delivery request receipt successful
400	InvalidParameter	Bad Request	Request parameter error Includes cases where the resources referenced by `templateNo`, `attachFileIds`, and`recipientGroupFilter.groups`.
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.
413	ContentTooLarge	Content Too Large	Request body size exceeded.
429	ResourceQuotaExceeded	Too Many Requests	Monthly delivery quota exceeded.
429	ThrottlingExceeded	Too Many Requests	Call frequency limit exceeded.
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:

{
"requestId": "20260702-R-01K0ZQ8YV3M4N5P6R7S8T9VAWX-777",
"requestCount": 1,
"createDateTime": "2026-07-02T10:00:00+09:00"
}