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

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

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

リクエスト

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

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

リクエストヘッダ

Simple & Easy Notification Service APIで共通して使用されるヘッダの詳細は、Simple & Easy Notification Serviceのリクエストヘッダをご参照ください。

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

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

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

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

リクエストボディ

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

フィールド	タイプ	必須の有無	説明
`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 最大100,000件まで入力可能 `TO`タイプの受信者1名以上必須 `recipientGroupFilter`未入力時は必須
`recipientGroupFilter`	Object	Conditional	アドレス帳グループに基づく受信者指定: 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です。その後の状態は、送信リクエストの照会 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 送信リクエストの照会、メールリストの照会 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"
}