---
title: "createMailRequest"
slug: "ai-application-service-cloudoutboundmailer-createmailrequest"
tags: ["Cloud Outbound Mailer"]
updated: 2026-09-17T09:35:44Z
published: 2026-09-17T09:35:44Z
canonical: "api.ncloud-docs.com/ai-application-service-cloudoutboundmailer-createmailrequest"
---

> ## 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.

# createMailRequest

Available in Classic and VPC

Request an email to be sent, specifying the recipient, sender, mail content, etc. The mailing operation is processed asynchronously.
Note

- You can send up to 100,000 recipients at a time, and it is processed in batches of 30 by default. However, you can send more than 100,000 recipients when you enter the recipient group combination sending condition (`recipientGroupFilter`).
- You can specify up to 30 recipients for Cc and Bcc.
- Email bodies are allowed to be up to 500 KB.
- The default sending limit is 1,000,000 per month, but you can request an increase through [Support](https://www.ncloud.com/support/question/service).
- The sending request limit is calculated based on the number of email recipients. A send request for 100 recipients is considered 100 send requests.

## Request

The following describes the request format for the endpoint. The request format is as follows:

| Method | URI |
| --- | --- |
| POST | /mails |

### Request headers

For information about the headers common to all Cloud Outbound Mailer APIs, see [Cloud Outbound Mailer request headers](/docs/en/ai-application-service-cloudoutboundmailer#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오. #요청헤더).

### Request body

The following describes the request body.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `senderAddress` | String | Conditional | Sender's email address - You can use any domain, but we recommend using a domain that the sender actually owns - Using a webmail account on a portal site with [DMARC](https://dmarc.org/overview/) applied, such as " id@naver.com," "id@navercorp.com," and "id@ncloud.com," might fail the DMARC check and be treated as spam according to the recipient's policies - Required when not setting `templateSid` - The domain cannot be naver.com. navercorp.com, etc. |
| `senderName` | String | Optional | Sender's name (byte) - 0 - 69 |
| `templateSid` | Integer | Optional | SID of the template you want to use to create the email - See [getTemplateStructure](/docs/en/ai-application-service-cloudoutboundmailer-gettemplatestructure) |
| `title` | String | Conditional | Email subject (byte) - 0 - 500 - Required if `templateSid` is not set |
| `body` | String | Conditional | Email body (KB) - 0 - 500 (Advertising emails are counted including unsubscribe messages) - Required if `templateSid` is not set |
| `individual` | Boolean | Optional | Whether to send generally or by individual - `true` (default) \| `false` - `true`: individual delivery - `false`: general delivery - You can only enter an `R` (recipient) in `recipients` when sending individually. When entering multiple values, they are sent separately to each individual |
| `confirmAndSend` | Boolean | Optional | Whether to send after confirmation - `true` \| `false` - `true`: send after confirmation - `false`: send immediately without confirmation |
| `advertising` | Boolean | Optional | Whether it is advertising email - `true` \| `false` - `true`: advertising email - `false`: general email |
| `parameters` | Object | Optional | Substitution parameter - It applies to all recipients - A map-type object with substitution IDs as keys and the values that map to the substitution IDs as values - See [User Guide](https://guide.ncloud-docs.com/docs/en/cloudoutboundmailer-use-mail#%EC%B9%98%ED%99%98-%ED%83%9C%EA%B7%B8-%EC%82%AC%EC%9A%A9) for the detailed application method |
| `referencesHeader` | String | Optional | References header - A string of 20 to 100 characters in the format of [unique_id@domain.com](mailto:unique_id@domain.com) - Unique value for collecting and viewing specific emails - If you enter a value in the field, you can collect and view only emails with the same value in the future. - It is used in NAVER Mail to collect and view emails - If the value is duplicated, it is determined to be the same email thread and the emails are grouped together - Only the topmost value of the References header is used to determine |
| `reservationUtc` | Long | Optional | Reserved delivery date and time - Number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC - Can be from the current point in time up to 30 days in the future - Take precedence over the `reservationDateTime` value |
| `reservationDateTime` | String | Optional | Reserved delivery date and time (yyyy-MM-dd HH:mm) - Based on UTC+9:00 - Can be from the current point in time up to 30 days in the future - The `reservationUtc` value takes precedence |
| `attachFileIds` | List[String] | Optional | ID list of attachments - Check the file ID through [createFile](/docs/en/ai-application-service-cloudoutboundmailer-createfile) - The total size of the files must be 20 MB or less |
| `recipients` | List | Conditional | Recipient list - Must be entered if there is no `recipientGroupFilter` value - See [RecipientForRequest](/docs/en/common-vapidatatype-nesrecipientrequest) |
| `recipientGroupFilter` | Object | Optional | Recipient group combination filter - See [RecipientGroupFilter](/docs/en/common-vapidatatype-nesrecipientgroupfilter) |
| `useBasicUnsubscribeMsg` | Boolean | Optional | Whether to use unsubscribe messages in advertising email - `true` (default) \| `false` - `true`: Use the default unsubscribe message - `false`: Use custom unsubscribe message - Unsubscribe message size is approximately 900 bytes |
| `unsubscribeMessage` | String | Conditional | Custom unsubscribe message text - Append after `body` value by default - Enter the `#{UNSUBSCRIBE_MESSAGE}` tag at the desired location in the `body` value to insert it inside the mail content - Required if the useBasicUnsubscribeMsg value is `false` - Must be 500 KB or less combined with `body` |

### Request example

The following is a sample request.

#### Create without template

The following is a sample request for writing your own email content without using a template.

```
curl --location --request POST 'https://mail.apigw.ntruss.com/api/v1/mails' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data-raw '{"senderAddress":"no_reply@company.com","title":"Hello, ${customer_name}.","body":"Your grade has been changed from ${BEFORE_GRADE} to ${AFTER_GRADE}.","recipients":[{"address":"hongildong@naver_.com","name":"Gildong Hong","type":"R","parameters":{"customer_name":"Gildong Hong","BEFORE_GRADE":"SILVER","AFTER_GRADE":"GOLD"}},{"address":"chulsoo@daum_.net","name":null,"type":"R","parameters":{"customer_name":"Chulsoo","BEFORE_GRADE":"BRONZE","AFTER_GRADE":"SILVER"}}],"individual":true,"advertising":false}'
```

#### Create with template

The following is a sample request for writing your own email content using a template.

```
curl --location --request POST 'https://mail.apigw.ntruss.com/api/v1/mails' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data-raw '{"templateSid" : 1,"recipients":[{"address":"hongildong@naver_.com","name":"Gildong Hong","type":"R","parameters":{"customer_name":"Gildong Hong","BEFORE_GRADE":"SILVER","AFTER_GRADE":"GOLD"}},{"address":"chulsoo@daum_.net","name":null,"type":"R","parameters":{"customer_name":"Chulsoo","BEFORE_GRADE":"BRONZE","AFTER_GRADE":"SILVER"}}],"individual":true,"advertising":false}'
```

## Response

The following describes the response format.

### Response body

The following describes the response body.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `requestId` | String | - | Email delivery request ID to distinguish each request - `requestId` can contain multiple `mailId` when requesting multiple mailings at once |
| `count` | Integer | - | Number of mailing requests |

### Response status codes

For information about the HTTP status codes common to all Cloud Outbound Mailer APIs, see [Cloud Outbound Mailer response status codes](/docs/en/ai-application-service-cloudoutboundmailer#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C).

### Response example

The following is a sample response.

```
{
  "requestId":"20181203000000000201",
  "count":10000
}
```