createMailRequest

Prev Next

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

受信者、送信者、メール内容などを指定してメール送信をリクエストします。送信は非同期で処理されます。
参考
  • 一度に最大100,000人に発送することができ、基本的に30件ずつ分けて処理されます。ただし、受信者グループ組み合わせ送信条件(recipientGroupFilter)を入力すると、100,000人を超えて送信することができます。
  • CCおよび BCCは最大30人ずつ追加できます。
  • メール本文は500KB以内で入力できます。
  • 基本送信限度は月1,000,000件です。サポートを通じて限度の引き上げをご依頼できます。
  • 送信リクエスト限度はメール受信者数に基づいて計算されます。100人の受信者に対する送信をリクエストすると、100件の送信リクエストとみなします。

リクエスト

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

メソッド URI
POST /mails

リクエストヘッダ

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

リクエストボディ

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

フィールド タイプ 必須の有無 説明
senderAddress String Conditional 送信者メールアドレス
  • 任意のドメインを使用できますが、送信者が実際に所有するドメインを使用することを勧告
  • DMARCが適用された「id@naver.com」といったポータルのウェブメールを使用する場合、DMARC検査に失敗して受信側のポリシーに基づいてスパム処理される可能性がある
  • templateSidを設定しない場合、必ず入力
  • ドメインに naver.com, navercorp.com, ncloud.comなどは使用不可
senderName String Optional 送信者名(Byte)
  • 0~69
templateSid Integer Optional メール作成に使用するテンプレートの SID
title String Conditional メールの件名(Byte)
  • 0~500
  • templateSidを設定しない場合、必ず入力
body String Conditional メール本文(KB)
  • 0~500(広告メールは受信拒否メッセージを含めてカウント)
  • templateSidを設定しない場合、必ず入力
individual Boolean Optional 一般送信か個別送信か
  • true (デフォルト) | false
    • true: 個別送信
    • false: 一般送信
  • 個別送信の場合、recipientsR(受信者)のみ入力可能。複数入力する場合、個別に分けて送信される。
confirmAndSend Boolean Optional 確認後に送信かどうか
  • true | false
    • true: 確認後に送信
    • false: 確認なしですぐ送信
advertising Boolean Optional 広告メールかどうか
  • true | false
    • true: 広告メール
    • false: 一般メール
parameters Object Optional 置換パラメータ
  • すべての受信者に適用
  • 置換 IDを Keyとして、置換 IDにマッピングする値を Valueとして持つ Map形式のオブジェクト
  • 適用方法の詳細は、ご利用ガイドを参照
referencesHeader String Optional Referencesヘッダ
  • 0~100個で、<unique_id@domain.com>形式の文字列
  • 特定のメールをまとめて見るための固有の値
  • フィールドに値を入力すると、その後に同じ値が入力されたメールだけまとめて照会可能
  • NAVERメールではメールをまとめて見るために使用
  • 値が重複する場合、同じメールスレッドと判断してメールをまとめて表示
  • Referencesヘッダの最上位値だけで判断
reservationUtc Long Optional 予約送信日時
  • 1970年1月1日 00:00:00 協定世界時(UTC)からの経過時間を1/1000秒に換算した整数
  • 現時点から最大30日後まで指定可能
  • reservationDateTime値より優先適用
reservationDateTime String Optional 予約送信日時(yyyy-MM-dd HH:mm)
  • UTC+9:00基準
  • 現時点から最大30日後まで指定可能
  • reservationUtc値が優先適用
attachFileIds List<String> Optional 添付ファイルの IDリスト
  • ファイル IDはcreateFileを通じて確認
  • ファイルの総容量は20MB以下まで
recipients List Conditional 受信者リスト
  • recipientGroupFilter値がない場合、必ず入力
recipientGroupFilter RecipientGroupFilter Optional 受信者グループの組み合わせフィルタ
useBasicUnsubscribeMsg Boolean Optional 広告メールで受信拒否メッセージを使用するかどうか
  • true (デフォルト) | false
    • true: デフォルト受信拒否メッセージを使用
    • false: ユーザー定義受信拒否メッセージを使用
  • 受信拒否メッセージのサイズは約900バイト
unsubscribeMessage String Conditional ユーザー定義受信拒否メッセージ
  • 基本的にbodyの末尾に追加
  • メール内容の中に挿入するには、bodyの目的の場所に#{UNSUBSCRIBE_MESSAGE}タグを入力
  • useBasicUnsubscribeMsgがfalseの場合、必須
  • bodyと合算して500KB以下にする

リクエスト例

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

テンプレートなしで作成

テンプレートを使用しないでメール内容を直接作成するリクエストのサンプルコードは次の通りです。

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":"${customer_name}様、こんにちは。","body":"お客様のランクが${BEFORE_GRADE}から${AFTER_GRADE}に変更されました。","recipients":[{"address":"hongildong@naver_.com","name":"田中太郎","type":"R","parameters":{"customer_name":"田中太郎","BEFORE_GRADE":"SILVER","AFTER_GRADE":"GOLD"}},{"address":"chulsoo@daum_.net","name":null,"type":"R","parameters":{"customer_name":"佐藤一郎","BEFORE_GRADE":"BRONZE","AFTER_GRADE":"SILVER"}}],"individual":true,"advertising":false}'

テンプレートを活用して作成

テンプレートを使用してメールを作成するリクエストのサンプルコードは次の通りです。

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":"田中太郎","type":"R","parameters":{"customer_name":"田中太郎","BEFORE_GRADE":"SILVER","AFTER_GRADE":"GOLD"}},{"address":"chulsoo@daum_.net","name":null,"type":"R","parameters":{"customer_name":"佐藤一郎","BEFORE_GRADE":"BRONZE","AFTER_GRADE":"SILVER"}}],"individual":true,"advertising":false}'

レスポンス

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

レスポンスボディ

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

フィールド タイプ 必須の有無 説明
requestId String Required リクエスト識別のためのメール送信リクエスト ID
  • 一度に複数件のメール送信をリクエストする場合、requestIdは複数のmailIdを含むことができる
count Integer Required メール送信リクエスト数

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

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

HTTPステータスコード コード 説明
201 - リクエスト成功
400 - 認証失敗、無効なリクエスト
400 77101 ログイン情報エラー
400 77102 リクエストエラー
400 77103 リクエストしたリソースが存在しない
403 77201 リクエストしたリソースに対する権限がない
403 77202 メールサービスの使用を申し込んでいないユーザーが呼び出した場合
405 77001 サポートしないメソッドタイプ
415 77002 サポートしないメディアタイプ
500 - サーバエラー
500 77301 基本プロジェクトが存在しない
500 77302 外部システム API連携エラー
500 77303 その他の内部サーバエラー

レスポンス例

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

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