---
title: "メール送信リクエストの作成"
slug: "sens-mail-request-create"
updated: 2026-10-08T07:15:47Z
published: 2026-10-08T07:15:47Z
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.

# メール送信リクエストの作成

Classic/VPC環境で利用できます。

メール送信をリクエストします。送信リクエスト1件につきリソースが1つ(`requestId`)作成され、送信は非同期で処理されるため、この APIは受付の結果のみを返します。

## リクエスト

リクエスト形式を説明します。リクエスト形式は次の通りです。

| メソッド | URI |
| --- | --- |
| POST | /mail/v2/services/{serviceId}/requests |

### リクエストヘッダ

Simple & Easy Notification Service APIで共通して使用されるヘッダの詳細は、[Simple & Easy Notification Serviceのリクエストヘッダ](/docs/ja/sens-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)をご参照ください。

| フィールド | 必須の有無 | 説明 |
| --- | --- | --- |
| `x-ncp-lang` | Optional | レスポンスメッセージの言語 - `en-US` (デフォルト)\| `ko-KR` \| `ja-JP` |

### リクエストパスパラメータ

リクエストパスパラメータの説明は次の通りです。

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `serviceId` | String | Required | メールサービス ID - NRN(NAVERクラウドプラットフォーム Resource Name)形式 (例: `ncp:mail:kr:1********2:main`) - [プロジェクトリストの照会](/docs/ja/sens-project-list)を参照 |

### リクエストボディ

リクエストボディの説明は次の通りです。

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `senderAddress` | String | Conditional | 送信者メールアドレス - 最大254Byte - `templateNo`未入力時は必須 |
| `senderName` | String | Optional | 送信者名 - 最大69Byte (UTF-8基準) |
| `templateNo` | Integer | Conditional | テンプレート番号 - 入力時、テンプレートに保存された送信者・件名・本文を使用 - `senderAddress`、`title`、`body`を併せて入力した場合、入力値がテンプレートの値を置き換え - 未入力時は`senderAddress`、`title`、`body`が必須 |
| `title` | String | Conditional | メール件名 - 最大500Byte(UTF-8基準) - `${key}`形式の置換変数を使用可能 - `templateNo`未入力時は必須 |
| `body` | String | Conditional | メール本文 - 最大500KB (UTF-8基準、置換変数が値に置換された後のサイズを受信者ごとに判定) - 広告メール(`advertising`が`true`)は受信拒否文言を含めてサイズを計算 - HTMLおよび`${key}`形式の置換変数を使用可能 - `templateNo`未入力時は必須 |
| `individual` | Boolean | Optional | 個別送信かどうか - `true` (デフォルト) \| `false` - `true`: 受信者ごとにメールを個別送信し、他の受信者のアドレスは表示されない - `false`: 複数の受信者を1つのメールにまとめて送信し、受信者同士でお互いのアドレスを確認可能 - `true`の場合、`CC`、`BCC`受信者は使用不可 |
| `confirmAndSend` | Boolean | Optional | 確認後送信するか - `true` \| `false` (デフォルト) - `true`: 送信準備状態で受付し、確認手続きを経て送信 |
| `advertising` | Boolean | Optional | 広告メールかどうか - `true` \| `false` (デフォルト) - `true`: 件名に広告表記が追加され、受信拒否案内が本文に含まれる - `individual`が`false`の一般送信では使用不可 |
| `parameters` | Object | Optional | 全受信者に共通して適用される置換変数 - `{"key": "value"}`形式 - 件名・本文の`${key}`が値に置換 - 入力時、受信者ごとの`recipients[].parameters`は適用されないｒ - 件名・本文に`${key}`がある場合、適用される側(リクエストレベルまたは受信者ごと)に当該キーがすべて存在する必要があり、キーが存在しない場合はリクエストが拒否される |
| `reservationDateTime` | String | Optional | 予約送信日時 - ISO 8601形式、タイムゾーンオフセット(`Z` 또는 `±hh:mm`)を含む(例: `2026-07-10T09:00:00+09:00`) - 未入力時は即時送信 - 現在時刻から最大30日後まで指定可能 |
| `attachFileIds` | Array | Optional | 添付ファイル IDリスト - 個々のファイルは最大10MB、合計は最大20MB |
| `recipients` | Array | Conditional | 受信者リスト: [recipients](/docs/ja/sens-mail-request-create#recipients) - 最大100,000件まで入力可能 - `TO`タイプの受信者1名以上必須 - `recipientGroupFilter`未入力時は必須 |
| `recipientGroupFilter` | Object | Conditional | アドレス帳グループに基づく受信者指定: [recipientGroupFilter](/docs/ja/sens-mail-request-create#recipientgroupfilter) - `individual`が`true`の個別送信でのみ使用可能 - `recipients`未入力時は必須 |
| `useBasicUnsubscribeMessage` | Boolean | Optional | 基本受信拒否文言を使用するかどうか - `true` (デフォルト) \| `false` - `true`: サービスが提供する基本受信拒否文言を使用 - `false`: `unsubscribeMessage`に入力した文言を使用 - 基本受信拒否文言のサイズは約900バイト - 広告メール(`advertising`が`true`)にのみ適用 |
| `unsubscribeMessage` | String | Optional | ユーザー指定の受信拒否文言 - `useBasicUnsubscribeMessage`が`false`の場合に適用 - `useBasicUnsubscribeMessage`が`false`であっても未入力時は基本受信拒否文言を適用 - 原則として`body`の後ろに追加され、本文内に挿入したい場合は`body`の希望する場所に`#{UNSUBSCRIBE_MESSAGE}`タグを入力 - `body`と合計して500KB以下にすること - 広告メール(`advertising`が`true`)にのみ適用され、一般メールには受信拒否文言が含まれない |

              参考

              

- `recipients`と`recipientGroupFilter`を両方入力すると、2つのリストを結合して処理され、同じアドレスが双方にあっても重複は削除されません。この場合、当該アドレスにメールが2通送信され、月間送信上限も2件差し引かれます。
- `recipientGroupFilter`で受信者を指定した場合、100,000名の件数上限は適用されず、月間送信上限のみが適用されます。
- `CC`と`BCC`はそれぞれ最大30名までです。
- 月間送信上限を超過した場合、`429 ResourceQuotaExceeded`が返されます。
- 受付レスポンスには送信状態は含まれていません。受付直後の状態は即時送信の場合は`READY`、予約送信の場合は`RESERVED`です。その後の状態は、[送信リクエストの照会](/docs/ja/sens-mail-request-get) APIをポーリングして確認します。ポーリング間隔は当該 APIの`retry-after`レスポンスヘッダに従います。

#### `recipients`

`recipients`の説明は次の通りです。

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `address` | String | Required | 受信者メールアドレス - 最大254Byte |
| `name` | String | Optional | 受信者名 - 最大69Byte(UTF-8基準) |
| `type` | String | Optional | 受信者タイプ - `TO` (デフォルト) \| `CC` \| `BCC` - `TO`: 宛先 - `CC`: CC(最大30名) - `BCC`: BCC(最大30名) - `individual`が`true`の場合、`CC`、`BCC`は使用不可 |
| `parameters` | Object | Optional | 当該受信者にのみ適用される置換変数 - `{"key": "value"}`形式 - リクエストレベルの`parameters`が入力されていない場合のみ適用 |

#### `recipientGroupFilter`

`recipientGroupFilter`の説明は次の通りです。

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `operator` | String | Optional | グループ条件結合演算子 - `OR` (デフォルト) \| `AND` - `OR`: 定したグループの1つ以上に所属する受信者 - `AND`: 指定したすべてのグループに所属する受信者 |
| `groups` | Array | Required | アドレス帳グループ名リスト |

### リクエスト例

リクエストのサンプルコードは次の通りです。

```
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": "サポートセンター",
"title": "${customer_name}様、こんにちは。",
"body": "お客様のランクが${BEFORE_GRADE}から${AFTER_GRADE}に変更されました。",
"individual": true,
"advertising": false,
"recipients": [
{
"address": "hongildong@example.com",
"name": "ホンギルドン",
"type": "TO",
"parameters": {
"customer_name": "ホンギルドン",
"BEFORE_GRADE": "SILVER",
"AFTER_GRADE": "GOLD"
}
}
],
"useBasicUnsubscribeMessage": true
}'
```

## レスポンス

レスポンス形式を説明します。

### レスポンスボディ

レスポンスボディの説明は次の通りです。

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `requestId` | String | - | 送信リクエスト ID - [送信リクエストの照会](/docs/ja/sens-mail-request-get)、[メールリストの照会](/docs/ja/sens-mail-list) APIのパスパラメータとして使用 - 値の内部構成は固定契約ではないため、パースせずそのまま使用 |
| `requestCount` | Integer | - | 送信メール件数 - 一般送信では受信者を分割して複数のメールを作成するため、受信者数と異なる場合がある - 個別送信(`individual`が`true`)の場合は受信者数と同じで |
| `createDateTime` | String | - | 送信リクエストの受付日時 - ISO 8601形式 |

### レスポンスステータスコード

レスポンスステータスコードの説明は次の通りです。

| HTTPステータスコード | コード | メッセージ | 説明 |
| --- | --- | --- | --- |
| 202 | - | Accepted | 送信リクエスト受付成功 |
| 400 | InvalidParameter | Bad Request | リクエストパラメータエラー - `templateNo`、`attachFileIds`、`recipientGroupFilter.groups`で指定されたリソースが使用できない場合を含む |
| 401 | Unauthorized | Unauthorized | 認証失敗 |
| 403 | Forbidden | Forbidden | パス内の`serviceId`に対する権限なし |
| 404 | NotFound | Not Found | パスのリソースが存在しない |
| 413 | ContentTooLarge | Content Too Large | リクエスト本文のサイズが上限を超過 |
| 429 | ResourceQuotaExceeded | Too Many Requests | 月間送信上限を超過 |
| 429 | ThrottlingExceeded | Too Many Requests | 呼び出し頻度制限を超過 |
| 500 | InternalServerError | Internal Server Error | サーバ内部エラー |

              参考

              

Simple & Easy Notification Serviceの他の APIと異なり、メール v2 APIは NAVERクラウドプラットフォーム API標準エラー形式でエラーを返します。レスポンスボディの`status`、`error`(文字列)フィールドではなく、以下の`error`オブジェクトが返されます。

#### エラーレスポンスボディ

呼び出しが失敗した場合のレスポンスボディの説明は次の通りです。

| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
| `error` | Object | - | エラー情報 |
| `error.errorCode` | String | - | エラーコード - レスポンスステータスコード表のコード列を参照 |
| `error.message` | String | - | エラーコードごとの固定メッセージ - `x-ncp-lang`ヘッダに指定した言語で返す |
| `error.detail` | String | - | リクエストごとの詳細理由 - 該当する理由がない場合はフィールドが省略される |
| `error.fieldErrors` | Array | - | パラメータ別エラーリスト - `field`: エラーが発生したパラメータの名前 - `message`: エラーの理由 - パラメータエラーでない場合はフィールドは省略される |

#### エラーレスポンス例

呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。

```
{
"error": {
"errorCode": "InvalidParameter",
"message": "The request contains an invalid parameter."
}
}
```

### レスポンス例

レスポンスのサンプルコードは次の通りです。

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