Create mail request

Available in Classic and VPC

Request to send mail. Each send request is created as one resource (requestId). Because sending is processed asynchronously, this API returns only the acceptance 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 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 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 saved in the template are used. If `senderAddress`, `title`, or `body` is entered together, the entered value replaces the template value. If not entered, `senderAddress`, `title`, and `body` are required.
`title`	String	Conditional	Mail subject Up to 500 bytes (UTF-8) Substitution variables in the `${key}` format can be used. Required if `templateNo` is not entered
`body`	String	Conditional	Mail body Up to 500 KB (UTF-8; the size is checked per recipient after substitution variables are replaced with values) For advertising mail (`advertising` is `true`), the size is calculated including the unsubscribe message. HTML and substitution variables in the `${key}` format can be used. Required if `templateNo` is not entered
`individual`	Boolean	Optional	Whether to send individually `true` (default) \| `false` `true`: send a separate mail to each recipient, so other recipients' addresses are not exposed `false`: send one mail to multiple recipients together, so recipients can see each other's addresses If `true`, `CC` and `BCC` recipients cannot be used.
`confirmAndSend`	Boolean	Optional	Whether to confirm before sending `true` \| `false` (default) `true`: accept the request in the ready-to-send state and send it after a separate confirmation step
`advertising`	Boolean	Optional	Whether the mail is an advertisement `true` \| `false` (default) `true`: an advertisement label is added to the subject and an unsubscribe notice is included in the body Cannot be used for group sending where `individual` is `false`
`parameters`	Object	Optional	Substitution variables applied to all recipients `{"key": "value"}` format `${key}` in the subject and body is replaced with the value. If entered, the per-recipient `recipients[].parameters` is not applied. If the subject or body contains `${key}`, every key must exist on the side that is applied (request level or per recipient). The request is rejected if a key is missing.
`reservationDateTime`	String	Optional	Reserved sending date and time ISO 8601 format including the time zone offset (`Z` or `±hh:mm`) (e.g., `2026-07-10T09:00:00+09:00`) If not entered, the mail is sent immediately. Can be set up to 30 days from the current time
`attachFileIds`	Array	Optional	List of attachment IDs Up to 10 MB per file, up to 20 MB in total
`recipients`	Array	Conditional	Recipient list: recipients Up to 100,000 recipients can be entered. At least one recipient of the `TO` type is required. Required if `recipientGroupFilter` is not entered
`recipientGroupFilter`	Object	Conditional	Recipients specified by address book group: recipientGroupFilter Can be used only for individual sending where `individual` is `true` Required if `recipients` is not entered
`useBasicUnsubscribeMessage`	Boolean	Optional	Whether to use the default unsubscribe message `true` (default) \| `false` `true`: use the default unsubscribe message provided by the service `false`: use the message entered in `unsubscribeMessage` The default unsubscribe message is about 900 bytes. Applies only to advertising mail (`advertising` is `true`)
`unsubscribeMessage`	String	Optional	Custom unsubscribe message Applied if `useBasicUnsubscribeMessage` is `false` If not entered, the default unsubscribe message is applied even when `useBasicUnsubscribeMessage` is `false`. Added after `body` by default. To insert it inside the body, enter the `#{UNSUBSCRIBE_MESSAGE}` tag at the desired position in `body`. The total size including `body` must be 500 KB or less. Applies only to advertising mail (`advertising` is `true`). Regular mail does not include an unsubscribe message.

Note

If both recipients and recipientGroupFilter are entered, the two lists are concatenated and processed. Duplicates are not removed even if the same address appears in both. In this case, two mails are sent to that address and two are deducted from the monthly sending limit.
If recipients are specified with recipientGroupFilter, the 100,000-recipient limit does not apply. Only the monthly sending limit applies.
CC and BCC are each limited to 30 recipients.
If the monthly sending limit is exceeded, 429 ResourceQuotaExceeded is returned.
The acceptance response does not include the sending status. Immediately after acceptance, the status is READY for immediate sending or RESERVED for reserved sending. Check the subsequent status by polling the Get mail request API. Follow the retry-after response header of that API for the polling interval.

`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) `BCC`: blind carbon copy (up to 30) If `individual` is `true`, `CC` and `BCC` cannot be used.
`parameters`	Object	Optional	Substitution variables applied only to this recipient `{"key": "value"}` format Applied only if the request-level `parameters` is not entered

`recipientGroupFilter`

The following describes recipientGroupFilter.

Field	Type	Required	Description
`operator`	String	Optional	Operator for combining group conditions `OR` (default) \| `AND` `OR`: recipients that belong to at least one of the specified groups `AND`: recipients that belong to all of the specified groups
`groups`	Array	Required	List of address book 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: en-US' \
--header 'Content-Type: application/json' \
--data '{
"senderAddress": "no_reply@company.com",
"senderName": "Customer Center",
"title": "Welcome, ${customer_name}.",
"body": "Your membership level has been changed from ${BEFORE_GRADE} to ${AFTER_GRADE}.",
"individual": true,
"advertising": false,
"recipients": [
{
"address": "hongildong@example.com",
"name": "Hong Gildong",
"type": "TO",
"parameters": {
"customer_name": "Hong Gildong",
"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	-	Send request ID Used as the path parameter of the Get mail request and Get mail list APIs The internal structure of the value is not a fixed contract. Use the value as is without parsing it.
`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 (`individual` is `true`), it equals the number of recipients.
`createDateTime`	String	-	Date and time the send request was accepted ISO 8601 format

Response status codes

The following describes the response status codes.

HTTP status code	Code	Message	Description
202	-	Accepted	Send request accepted successfully
400	InvalidParameter	Bad Request	Request parameter error Includes cases where the resource referenced by `templateNo`, `attachFileIds`, or `recipientGroupFilter.groups` cannot be used
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
413	ContentTooLarge	Content Too Large	Request body size exceeded
429	ResourceQuotaExceeded	Too Many Requests	Monthly sending limit exceeded
429	ThrottlingExceeded	Too Many Requests	Call rate limit exceeded
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:

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