---
title: "Create email delivery request"
slug: "sens-mail-request-create"
updated: 2026-10-08T04:15:06Z
published: 2026-10-08T04:15:06Z
canonical: "api.ncloud-docs.com/sens-mail-request-create"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/en/sens-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94).

| 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](/docs/en/sens-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](/docs/en/sens-mail-request-create#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](/docs/en/sens-mail-request-create#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](/docs/en/sens-mail-request-get) 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](/docs/en/sens-mail-request-get) and [Get email list](/docs/en/sens-mail-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"
}
```