機能説明
送信するメールの文面を登録します。
1度のリクエストで、最大1000通の配信メールを登録することができます。
リクエスト
エンドポイント
/v1/mails
HTTPメソッド
POSTもしくはPUT
リクエストボディ
JSON形式であること
リクエスト
要素名
|
型
|
要素数
|
制限
|
説明
|
---|---|---|---|---|
envelopes | Envelope型の配列 | 1:1000 | - | 宛先メールアドレスごとのメタデータの配列 |
from | メールアドレス型 | 1 | - | Fromヘッダの値 |
reply_to | メールアドレス型 | 0:1 | - | Reply-Toヘッダの値 |
subject | 文字列 | 1 |
|
Subjectヘッダの値 |
body | Body型 | 1 |
以下のいずれかの方式でエンコードされていること
|
メール本文 |
attachment | Attachment型の配列 | 0:32 | - | 添付ファイル |
custom_args | キー文字列・値文字列のハッシュ | 0:100 |
|
メール1件ごとに保持する独自データ |
headers | キー文字列・値文字列のハッシュ | 0:* |
|
カスタムメールヘッダ |
replace_value | キー文字列・値のハッシュ | 0:100 |
|
差し込み変換用データ
下記の項目でも使用可能だが、改行が含まれていた場合は半角空白に置換されます。
改行は、LFもしくはCRLFを使用すること |
timestamp | 数値 | 0:1 |
|
送信時刻 |
batch_id | 文字列 | 0:1 |
|
複数のメールを1配信として扱うための文字列 |
tracking | トラッキング設定 | 0:1 | - |
メール文面中のリンク及びHTMLパートのビーコン画像によるトラッキング設定
本文から抽出可能なURLの数は、TEXTパート、HTMLパートそれぞれ100個まで 文面の先頭から数えて100種類までのURLがトラッキングURLに置換されます。 |
dkim | DKIM署名設定 | 0:1 | - |
メールに署名するDKIMのセレクタを指定するための設定
|
defer_limit | 数値 | 0:1 |
|
一時配送エラー時のメール再送試行回数を指定するための設定
メール配信設定で設定できる再送回数の設定より優先して設定されます。 この値を指定しない場合、メール配信設定で設定できる再送回数分だけ再送されます。 この値を指定する場合の詳細な挙動については、メール配信設定更新の項目を参照すること。
|
Envelope
要素名
|
型
|
要素数
|
制限
|
説明
|
---|---|---|---|---|
to | メールアドレス型 | 1 | 1APIコールでto,cc,bcc合計で1000アドレス以内 | 宛先アドレス |
cc | メールアドレス型の配列 | 0:100 | 1APIコールでto,cc,bcc合計で1000アドレス以内 | CCアドレス |
bcc | メールアドレス型の配列 | 0:100 | 1APIコールでto,cc,bcc合計で1000アドレス以内 | BCCアドレス |
from | メールアドレス型 | 0:1 | - | Fromヘッダの値 上階層のfromより優先して設定されます。 |
reply_to | メールアドレス型 | 0:1 | - | Reply-Toヘッダの値 上階層のReply-Toより優先して設定されます。 |
subject | 文字列 | 0:1 |
|
Subjectヘッダ
上階層のsubjectより優先して設定されます。 |
headers | キー文字列・値文字列のハッシュ | 0:* |
|
カスタムメールヘッダ
上階層のheadersに英字の大文字・小文字を無視した同名の項目が存在する場合、この設定が優先されます。 |
replace_value | キー文字列・値文字列のハッシュ | 0:100 |
|
差し込み変換用データ
上階層のreplace_valueに同一名の項目が存在する場合、この設定が優先されます。 下記の項目で使用可能です。
下記の項目でも使用可能だが、改行が含まれていた場合半角空白に置換されます。
改行はLFもしくはCRLFを使用すること
※LFは自動的にCRLFに変換される |
custom_args | キー文字列・値文字列のハッシュ | 0:100 |
|
宛先メールアドレスごとに保持する独自データ
上階層のcustom_argsに同一名の項目が存在する場合、この設定が優先されます。 |
tracking | 宛先別トラッキング設定 | 0:1 | - |
宛先別のトラッキング設定
大元のtrackingの有効・無効に関わらず入力値の検証が実行されます。 |
dkim | DKIM署名設定 | 0:1 | - |
メールに署名するDKIMのセレクタを指定するための設定
上階層のdkimより優先して設定されます。 |
メールアドレス
要素名
|
型
|
要素数
|
制限
|
説明
|
---|---|---|---|---|
address | 文字列 | 1 |
|
メールアドレス
|
name | 文字列 | 0:1 |
|
メールアドレスの名称パート |
Body
要素名
|
型
|
要素数
|
制限
|
説明
|
---|---|---|---|---|
text | 文字列 | 0:1 |
|
テキストパート文面
改行はLFもしくはCRLFを使用すること ※LFは自動的にCRLFに変換されます。
※差し込みによってコンテンツサイズ上限を超過するとシステムが判断した場合、その旨を記載したエラーを返します。 ※差し込みによって1行が10000文字を超過する行が存在するとシステムが判断した場合、その旨を記載したエラーを返します。 |
html | 文字列 | 0:1 |
|
HTMLパート文面
改行はLFもしくはCRLFを使用すること ※LFは自動的にCRLFに変換されます。 ※差し込みによってコンテンツサイズ上限を超過するとシステムが判断した場合、その旨を記載したエラーを返します。 ※差し込みによって1行が10000文字を超過する行が存在するとシステムが判断した場合、その旨を記載したエラーを返します。 |
Attachment
要素名
|
型
|
要素数
|
制限
|
説明
|
---|---|---|---|---|
content | 文字列 | 1 |
|
base64エンコード済みのファイルのバイナリ |
name | 文字列 | 1 |
|
ファイル名 |
type | 文字列 | 1 |
|
MIMEタイプ |
disposition | 文字列 | 0:1 |
|
添付ファイルの表示方法 |
content_id | 文字列 | 0:1 |
|
メール本文でファイルを参照するためのID |
トラッキング
要素名
|
型
|
要素数
|
制限
|
説明
|
---|---|---|---|---|
tracking | 文字列 | 1 |
|
トラッキングを有効にするフラグ
may サーバ障害などが原因でトラッキングURLが取得できなかった場合に文面生成を続行します。 must トラッキングURLが取得できなかった場合は文面生成を中止します。 |
beacon | boolean | 0:1 | - |
メール開封確認用の、HTMLパートにビーコン画像を付与するためのフラグ
このフラグをtrueにした状態でHTMLパートが存在しない場合は無視されます。 |
expires | トラッキング有効期限の配列 | 0:1 | - | トラッキングするURLの有効期限設定 |
custom_domain | 文字列 | 0:1 |
|
トラッキングURLに使用するドメイン
※利用の際は下記「カスタムドメイン設定」を確認すること
必要な準備を行わずに設定した場合は、トラッキング機能が正常に動作しません。 |
harelay | キー文字列・値文字列のハッシュ | 0:1 |
|
トラッキングURLから元URLにリダイレクトする際に経由させるURL設定
|
replace_url | 文字列の配列 | 0:100 |
|
本文に含まれるURLのうち、配列中に含まれるURLのみをトラッキングURLに置換します。 この項目が存在しない場合、または空配列の場合、本文に含まれる全てのURLをトラッキングURLに置換します。 |
トラッキング有効期限
要素名
|
型
|
要素数
|
制限
|
説明
|
---|---|---|---|---|
url | 文字列 | 1 |
|
有効期限を設定するURL
URL形式か、 beaconという文字列である必要があります。 beaconを指定した場合、beaconの有効期限を設定することになります。 |
timestamp | 数値 | 1 |
|
有効期限を示す日時のunixタイムスタンプ秒
現在時刻から31日後までである必要があります。 現在以前、もしくは31日後より後を指定した場合、自動で31日後に上書きされます。 |
redirect | 文字列 | 1 |
|
有効期限が切れた場合にリダイレクトするURL
urlでbeaconを指定した場合に限り、指定する必要はありません(無視される)。 |
宛先別トラッキング設定
要素名
|
型
|
要素数
|
制限
|
説明
|
---|---|---|---|---|
label1 | 文字列 | 0:1 |
|
結果取得時の抽出用ラベル1 |
label2 | 文字列 | 0:1 |
|
結果取得時の抽出用ラベル2 |
label3 | 文字列 | 0:1 |
|
結果取得時の抽出用ラベル3 |
query | キー文字列・値文字列のハッシュ | 0:1 |
|
トラッキングURLから元URLにリダイレクトする際にクエリパラメータとして付与する設定
|
DKIM署名
要素名
|
型
|
要素数
|
制限
|
説明
|
---|---|---|---|---|
selector | 文字列 | 1 |
|
DKIM署名のセレクター
ドメインは、fromで指定したアドレスのドメインが対象となります。 |
リクエストボディのサンプル
{
"envelopes": [
{
"to": {"name":"宛先", "address": "to@example.net"},
"cc": [{"name":"CC宛先", "address": "cc@example.net"}],
"bcc": [{"name":"BCC宛先", "address": "bcc@example.net"}],
"subject": "個別サブジェクト",
"headers": {
"x-sample": "overwrite-root-headers-value"
},
"replace_value": {
"#REPLACE#": "こちらが優先して置換されます",
"#SUBJECT#": "こちらが優先して置換されます",
"#FROM#": "こちらが優先して置換されます",
"#REPLY-TO#": "こちらが優先して置換されます"
},
"custom_args": {
"user_id": "00001"
},
"tracking": {
"query": {
"user_id": "1234",
"email": "to@example.net"
}
}
}
],
"from": {"address": "from@exmaple.net", "name": "差出人 #FROM#"},
"reply_to": {"address": "reply@example.net", "name": "返信先 #REPLY-TO#"},
"subject": "サンプルメール #SUBJECT#",
"body": {
"text": "これはテキストパートです\n#REPLACE#",
"html": "<p>これは<strong>HTML</strong>パートです<br/>#REPLACE#<br/><img src=\"cid:dot@example.net\"/></p>"
},
"attachment": [
{
"content": "R0lGODlhAQABAIAAAAUEBAAAACwAAAAAAQABAAACAkQBADs=",
"name": "ドット.gif",
"type": "image/gif",
"dispostion": "inline",
"content_id": "dot@example.net"
}
],
"custom_args": {
"user_id": "00000"
},
"headers": {
"x-sample": "sample"
},
"replace_value": {
"#REPLACE#": "置換されます",
"#SUBJECT#": "Subjectが置換されます",
"#FROM#": "Fromが置換されます",
"#REPLY-TO#": "Reply-Toが置換されます"
},
"timestamp": 1514732400,
"batch_id": "IDA001",
"tracking": {
"tracking": "may",
"beacon": true,
"expires": [
{
"url":"https://example.com",
"timestamp": 1546182000,
"redirect": "https://example.org"
}
],
"custom_domain": "click.mydomain.org",
"relay": {"r":"https://example.jp"}
},
"dkim": {
"selector": "myselector"
}
}
レスポンス
ステータスコード
状態
|
コード
|
---|---|
成功 | 200 |
リクエストボディがjsonではない | 400 |
jsonリクエストのバリデーションエラー | 400 |
認証失敗 | 401 |
存在しないエンドポイント | 404 |
許可されていないHTTPメソッド | 405 |
システムエラーが発生した | 500 |
システムが一時的にサービスを提供できない状態になっている | 503 |
システムのタイムアウト | 504 |
レスポンスボディ
成功
{"code":200}
失敗
{"code":400,"error":"validation error", "validation_errors":"subject required"}
共通設定と宛先別設定
custom_args headers replace_value subjectは、全宛先共通の設定とenvelopes.*で設定する宛先別設定が存在します。
いずれの設定も、共通設定と宛先別設定で同名の項目があった場合、宛先別設定が優先されます。
headersに限り、名前の同一判定において大文字・小文字を無視します。
例
リクエスト
{
...
"from": {"address":"from@example.com"}
"subject":"root subject",
"headers":{"x-header":"root"},
"custom_args":{"arg1":"root"},
"replace_value":{"#R#","root"},
"envelopes": [
{
"to": {"address":"to@example.com"},
"subject":"envelope subject #R#",
"headers":{"X-HEADER":"envelope"},
"custom_args":{"arg1","envelope"},
"replace_value":{"#R#","envelope"}
}
],
"body":{"text":"body #R#"},
...
}
送信されるメール文面
メールヘッダ:
From: <from@example.com>
To: <to@example.com>
Subject: envelope subject envelope
X-HEADER: envelope
メール本文:
body envelope
通知されるwebhook
{
"mta_mail_id":"9999999999",
"email":"to@example.com",
"timestamp":1507785394,
"custom_args":{"arg1":"envelope"},
"event":"Delivered",
"batch_id":"sample."
}
差し込み置換
replace_value envelopes.*.replace_valueに、対象文字列と置換後の文字列を設定することで、
body.html body.text subject from.name reply_to.name envelopes.*.subjectの対象文字列を置換することができます。
replace_value envelopes.*.replace_valueに、同名の置換対象文字列が存在する場合、宛先別設定であるenvelopes.*.replace_valueを優先します。
また、置換後の文字列に改行が含まれていて、subject from.name reply_to.nameに差し込んだ場合、改行が半角空白に変換されます。
例
リクエスト
...
"replace_value":{"#REPLACE0#":"これはrootの0です","#REPLACE1#":"これはrootの1です"},
"from":{"address":"from@example.com":"name":"#REPLACE1#"},
"reply_to":{"address":"reply@example.com":"name":"#REPLACE0#"},
"body":{"text":"#REPLACE0#,#REPLACE1#,#REPLACE2#"},
"subject":"#REPLACE2#",
"envelopes":[
{
"to":{"address":"to@example.com"},
"replace_value":{"#REPLACE1":"これはenvelopeの1です","#REPLACE2#":"改行前\n改行後"},
"subject":"#REPLACE1#"
}
],
...
送信されるメール文面
メールヘッダ:
From: "これはenvelopeの1です" <from@example.com>
To: <to@example.com>
Reply-To: "これはrootの0です" <reply@example.com>
Subject: 改行前 改行後
メール本文:
これはrootの0です,これはenvelopeの1です,改行前
改行後
#REPLACE0#は、共通設定しか存在しないため、「これはrootの0です」となります。
#REPLACE1#は、envelopes.0に宛先別設定が存在するため、envelopes.0宛てのメールでは「これはenvelopeの1です」となります。
#REPLACE2#は共通設定には存在せず、envelopes.0にのみ存在するため、envelopes.0宛てのメールでは「改行前<CR><LF>改行後」となります。
メール送信に必要な入力項目
最低限のメール送信に必要な入力項目と、メール送信可能となる条件は下記の通りです。
- subjectに、バリデーションエラーにならない文字列が設定されていること
- from.addressに、バリデーションエラーにならないメールアドレスが設定されていること
- body.text、もしくはbody.htmlにバリデーションエラーにならない文字列が設定されていること
- envelopes.*.to.addressに、バリデーションエラーにならないメールアドレスが設定されていること
例
リクエスト
{
"subject": "this is minimum request",
"from": {"address":"from@example.com"},
"body": {"text": "minimum request body."},
"envelopes": [
{"to":{"address":"to@example.com"}}
]
}
購読解除リンクの表示に必要なヘッダの指定
List-UnsubscribeおよびList-Unsubscribe-Postヘッダを付与することで、RFC8058の要件「The List-Unsubscribe and List-Unsubscribe-Post headers MUST be covered by the signature and included in the "h=" tag of a valid DKIM-Signature header field.」をクリアしたメールを送信することができます。
例
リクエスト
{
"subject": "サブジェクト",
"from": {"address": "from@example.com"},
"envelopes": [
{"to": {"address": "to@example.com"}}
],
"headers": {
"List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
"List-Unsubscribe": "<https://example.com/r?store_id=1>,<mailto:notify@example.com>"
},
"body": {
"text": "これはテキストパートです",
"html": "これはHTMLパートです"
}
}
送信されるメールのヘッダ
From: <from@example.com>
To: <to@example.com>
Subject: サブジェクト
...
DKIM-Signature: ... ; h=From:To:Subject:Message-Id:List-Unsubscribe:List-Unsubscribe-Post; ...
List-Unsubscribe: <https://example.com/r?store_id=1>,<mailto:notify@example.com>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
...
トラッキングURLの有効化
トラッキングURLの設定を有効にすると、テキストパート及びHTMLパート文面中のURLが、トラッキングURLに置換されて送信されます。
テキストパートではURL文字列を置換し、HTMLパートではaタグのhref属性の文字列をトラッキングURLに置換します。
また、トラッキング設定のbeacon項目を有効にすることで、HTMLパート文面にHTMLメール開封確認用のビーコン画像が追加されます。
テキストパート
API時の文面リクエスト
サンプルメールです
https://example.org
送信される文面(URLのxおよびyの部分はランダム)
サンプルメールです
https://tracking.autobahn.email/v2/r/xxxxxx/yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
HTMLパート
API時の文面リクエスト
<html>
<body>
<p>
サンプルメールです<br>
<br>
<a href="https://example.org">リンク</a><br>
<span>https://example.com</span>
</p>
</body>
</html>
送信される文面(URLのxおよびyの部分はランダム)
<html>
<body>
<p>
サンプルメールです<br>
<br>
<a href="https://tracking.autobahn.email/v2/r/xxxxxx/yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy">リンク</a><br>
<span>https://example.com</span>
</p>
<img src="https://tracking.autobahn.email/v2/b/xxxxxx/yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"/>
</body>
</html>
抽出用設定
各トラッキングURL、及び開封ビーコンURLには自動的にメールIDとバッチIDが付与されます。
このため、トラッキング・開封結果取得APIでメールIDまたはバッチIDを指定した場合、該当するデータのみを取得することができます。
また、宛先別トラッキング設定のlabel1・label2・label3に、任意の文字列を設定することで特定のラベルのトラッキング結果を抽出することができます。
カスタムドメイン設定
トラッキング用URLのドメインは、tracking.autobahn.email(試用環境は tracking-dev.autobahn.email)だが、トラッキング設定内のcustom_domainにドメインを指定することで、トラッキング用URLのドメインを変更することができます。
ただし、下記の事前準備が必要です。
個別対応となるため、事前にトライコーンの担当営業と協議を行ってください。
- CNAMEレコードの設定
- カスタムドメインとして利用するドメインの、CNAMEレコードを設定する
- 値は、tracking.autobahn.emailと設定する
- カスタムドメインのSSL/TLSサーバ証明書を用意し、autobahn MTAシステムへ適用(有償)
- 適用後、証明書の期限が切れるたびに都度の適用作業が発生する点に留意
※本番環境のみ利用することができ、試用環境では利用できないオプションです。
トラッキングURLの置換処理
テキスト、HTMLのパートによって置換処理のルールが異なります。
テキストパート
下記の場合は、URLが置換対象にならない、もしくは置換対象URLの欠落が発生する場合があります。
- 1行が一定サイズを超える長さで、一定サイズの閾値にURL文字列が含まれる
- URLの途中で改行している
- URLの直前が、行頭または半角空白ではない
https://example.com?id=hoge[CR][LF]
↑リンク
---
https://example.com?id=hogeが置換対象
https://example.com?id=[CR][LF]
hoge
↑リンク
---
https://example.com?id=が置換対象
...hoge.hoge https://example.com?id=hoge
一定の長さ ↑ URL文字列の途中で処理を跨ぐ
---
https://example.com?id=が置換対象
(https://example.com?id=hoge[CR][LF]
---
URL 直前に "(" があるため置換が行われない。"(" を消したり、半角空白を間にいれると https://example.com?id=hoge[CR][LF] が置換対象となる
HTMLパート
下記の場合は、URLが置換対象にならない、もしくは置換対象URLの欠落が発生する場合があります。
- aタグのタグ開始
- <a直後に改行している
<a href="https://example.com?id=hoge">リンク</a>
---
https://example.com?id=hogeが置換対象
<a name="hoge"[CR][LF]
href="https://example.com?id=hoge">リンク</a>
---
aタグ開始後、半角スペース等が含まれるためhttps://example.com?id=hogeが置換対象
<a[CR][LF]
href="https://example.com?id=hoge">リンク</a>
---
置換対象にならない
...hoge.hoge<a href="https://example.com?id=hoge">リンク>
一定の長さ ↑ aタグの途中で処理を跨ぐ
---
https://example.com?id=hogeが置換対象