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

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(NCP Resource Name)形式(例: `ncp:mail:kr:1********2:main`) プロジェクトリストの照会を参照

リクエストボディ

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

フィールド	タイプ	必須の有無	説明
`senderAddress`	String	Conditional	送信者のメールアドレス最大254 Byte `templateNo`を入力しない場合は必須
`senderName`	String	Optional	送信者名最大69 Byte(UTF-8基準)
`templateNo`	Integer	Conditional	テンプレート番号入力すると、テンプレートに保存された送信者・件名・本文を使用 `senderAddress`、`title`、`body`を一緒に入力すると、入力値がテンプレートの値を上書き入力しない場合は`senderAddress`、`title`、`body`が必須
`title`	String	Conditional	メールの件名最大500 Byte(UTF-8基準) `${key}`形式の置換変数を使用可能 `templateNo`を入力しない場合は必須
`body`	String	Conditional	メールの本文最大500 KB(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リストファイルごとに最大10 MB、合計最大20 MB
`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`と合算して500 KB以下である必要がある広告メール(`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	受信者のメールアドレス最大254 Byte
`name`	String	Optional	受信者名最大69 Byte(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`: 指定したグループのいずれかに属する受信者 `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: ja-JP' \
--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": "yamada@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は NCP 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"
}