目次
メールコンテンツ新規作成APIとは
本APIの概要
メールコンテンツ新規作成APIとは、貴社の基幹システム/アプリケーションとb→dashを繋ぐことでb→dash管理画面を介さずにメールアプリの機能の1つであるメールコンテンツの新規作成をすることができるAPIです。
貴社の基幹システム/アプリケーションに連携したメールコンテンツの作成を行いたい場合は、本API仕様書をご参照のもと貴社開発環境に実装してください。
本APIで作成できるb→dash管理画面上のデータ
b→dash管理画面と同等の操作
メールコンテンツ新規作成APIでは、b→dash管理画面にある「メールコンテンツ新規作成画面(以下キャプチャ)」における操作と同様に、「HTML/テキストメール(マルチパート)」「HTMLメール」「テキストメール」の作成を行うことができます。
※ただし本APIでは「HTML/テキストメール(マルチパート)」「HTMLメール」のテンプレート機能を用いたメールコンテンツの作成はできないためご注意ください
メールコンテンツ新規作成画面の例
「HTML/テキストメール(カスタマイズ・GUI編集モード)」「テキストメール」編集画面の例
「HTML/テキストメール(カスタマイズ・HTML編集モード)」「テキストメール」編集画面の例
b→dash管理画面上の更新結果確認方法
メールコンテンツ新規作成APIを利用した結果は以下のb→dash管理画面(「メールコンテンツ一覧画面」「メールコンテンツ詳細画面(更新履歴モーダル)」)で確認することができます。
メールコンテンツ一覧画面の例
メールコンテンツ詳細画面(更新履歴モーダル)の例
本API利用にあたっての前提事項
共通仕様
メールコンテンツ新規作成APIでは、b→dash APIの共通仕様も参照する必要があります。共通仕様の詳細については「b→dash APIの共通仕様を知りたい」をご参照ください。
非機能要件
メールコンテンツ新規作成APIでは、下記の非機能要件を持ちます。「全体サイズ上限」の項目のみb→dashAPIの共通仕様と異なるため、ご確認ください。
# | 項目 | 非機能要件 |
1 | URI長の上限 |
10KBまで
(共通仕様同様) |
2 | 全体サイズ上限 | 1000kbまで |
3 | レスポンス |
リクエストからレスポンスの間は5秒以内
(共通仕様同様) |
4 | 月間リクエスト上限数 |
10万リクエストまで
※超過した場合でも、エラーになりません (共通仕様同様) |
5 | 分間リクエスト上限数 |
100リクエストまで
(共通仕様同様) |
6 | レート制限 |
20秒あたり100リクエストまで
(共通仕様同様) |
7 | 同時接続上限数 |
5リクエストまで
(共通仕様同様) |
8 | タイムアウト |
60秒まで (共通仕様同様) |
※上限数は、1アカウント内の上限とします
メールコンテンツ新規作成APIの仕様
処理フロー図
メールコンテンツ新規作成APIの処理フロー図は以下になります。
メールコンテンツ新規作成リクエスト
json形式のファイル(拡張子:.json)にリクエストボディパラメータを指定して、メールコンテンツの更新内容を送信するためのリクエストボディを準備します
〇リクエストボディパラメータ
プロパティ |
型
/サイズ |
必須 | 値 | 説明 |
contents_name |
string /255字 |
○ | {メールコンテンツ名称} |
登録するメールコンテンツの名称
※255文字以内 |
subject |
string /255字 |
○ | {件名} |
件名
※255文字以内 |
type |
string /5字 |
○ |
MULTI,
HTML, TEXT |
メールのタイプ
・マルチパートメール:「MULTI」 ・HTMLメールのみ:「HTML」 ・テキストメールのみ:「TEXT」 |
body_html_part |
string /800kb |
△ |
本文(HTMLパート)
メールのHTMLパートの本文に利用するHTMLコードを 「メール編集画面_直接編集モード」の本文に入力した場合と同等 ※メールのタイプが「マルチパートメール」 または「HTMLメールのみ」の場合は必須 |
|
body_text_part |
string /100kb |
△ |
本文(テキストパート)
・メールのテキストパートの本文としてそのまま利用する ・「メール編集画面_テキストメール」の本文に入力した場合と同等とする ※メールのタイプが「マルチパートメール」 または「テキストメールのみ」の場合は必須 |
|
memo |
string /10000字 |
- |
メモ
※10000文字以内 |
|
is_shorten_url |
boolean /5 |
- |
true,
false |
URLを短縮URLにするか(短縮URL化の流れは後述)
短縮URLにする:「true」 短縮URLにしない:「false」 ※未設定時:「false」 |
custom_domain_name |
string /255 |
- |
短縮URLに使用するカスタムドメイン設定で登録されているドメイン(FQDN)
「custom_domain_name」が未設定の場合は、デフォルトのドメインを利用する ※ 255文字以内 |
【リクエストボディサンプル】
{
"contents_name": "メールA",
"subject": "テスト用メール",
"type": "MULTI",
"body_html_part": "<!DOCTYPE html>n<html>n<head>n<meta charset="utf-8">n</head>n<body>n<p>HTMLの本文です。</p><p><a href="https://example.com/abc">リンク</a></p></body>n</html>",
"body_text_part": "XXX様nnテストメールnnhttps://example.com/xyznnhttps://example.com/abc",
"memo": "メモ",
"is_shorten_url": true,
"custom_domain_name": "short.domain"
}
メールコンテンツ新規作成APIのURIと、準備したリクエストボディ、下記のリクエストヘッダパラメータを用いて、貴社Webアプリから「POST」リクエスト形式でメールコンテンツ新規作成のリクエストをします
〇メールコンテンツ新規作成APIのURI
URI | https://api.smart-bdash.com/api/v1/mail_contents |
〇リクエスト形式
HTTPメソッド | POST |
〇リクエストヘッダパラメータ
プロパティ |
型
/サイズ |
必須 | 値 | 説明 |
Authorization |
string
/2055文字 |
◯ | Bearer {アクセストークン} | 「認証方式を選択したい」で取得したアクセストークン |
Content-Type |
string
/固定値 |
◯ | application/json; charset=UTF-8 | 固定値 |
【リクエストコードサンプル】
POST https://api.smart-bdash.com/api/v1/mail_contents
メールコンテンツ新規作成レスポンス
リクエストの送信に成功すると、下記のレスポンス形式でメールコンテンツ新規作成APIからレスポンスが返されます
〇レスポンスボディパラメータ
パラメータ名 | Key | データ型 | 説明 |
階層1:result | object | - | |
階層2:code | integer($int32) | ステータスコード | |
階層2:contents_id | string | 作成されたメールコンテンツのID | |
階層2:contents_name | string |
作成されたメールコンテンツの名称
APIリクエスト時に指定したメールコンテンツの名称が 既に使用されている場合は、以下のルールで命名される {APIリクエスト時のメールコンテンツの名称}(n) ※「n」は名称が重複したメールコンテンツごとの連番とし、 「1」から採番を開始する |
|
階層2:body_html_part | string |
作成されたメールコンテンツの本文(HTMLパート)
APIリクエストで「type」に「TEXT」を指定した場合、空文字 ※短縮URLコンテンツが新規作成された場合、 または「スキップされたURL」に合致する場合は 元のURLは短縮後のURLで置換した内容となる |
|
階層2:body_text_part | string |
作成されたメールコンテンツの本文(テキストパート)
APIリクエストで「type」に「HTML」を指定した場合、空文字 ※短縮URLコンテンツが新規作成された場合、 または「スキップされたURL」に合致する場合は 元のURLは短縮後のURLで置換した内容となる |
|
階層2:target_url_count | integer($int32) | 判定対象URL数(=短縮URL発行数+スキップされたURL数) | |
階層2:shortened_url_count | integer($int32) | 短縮URL発行数 | |
階層2:skipped_url_count | integer($int32) | スキップされたURL数 | |
階層2:short_url_contents | object[] |
作成された短縮URLコンテンツの一覧
作成された短縮URLコンテンツが存在しない場合、空の配列 |
|
階層3:id | string | 作成された短縮URLコンテンツのID | |
階層3:name | string | 作成された短縮URLコンテンツの名称 | |
階層3:short_url | string | 発行された短縮URL | |
階層3:actual_url | string | 短縮前のURL |
〇リクエストエラー発生時のエラーメッセージ詳細
# | コード | エラーメッセージ | 説明 |
1 | 400 | contents_nameは必須です。255文字以内で指定してください。 | メールコンテンツの名称が未設定 |
2 | 400 | contents_nameは255文字以内で指定してください。 | メールコンテンツの名称が255文字を超過した |
3 | 400 | subjectは必須です。255文字以内で指定してください。 | 件名が未設定 |
4 | 400 | subjectは255文字以内で指定してください。 | 件名が255文字を超過した |
5 | 400 | typeは必須です。以下のいずれかを指定してください。MULTI/HTML/TEXT | メールのタイプが未設定 |
6 | 400 | typeには以下のいずれかを指定してください。MULTI/HTML/TEXT | メールのタイプに不正な文字列が指定された |
7 | 400 | type「{type}」を指定時はbody_html_partが必須です。body_html_partを指定してください。 | メールのタイプが「マルチパートメール」または「HTMLメールのみ」で 本文(HTMLパート)が未設定 |
8 | 400 | type「{type}」を指定時はbody_text_partが必須です。body_text_partを指定してください。 | メールのタイプが「マルチパートメール」または「テキストメールのみ」で 本文(テキストパート)が未設定 |
9 | 400 | コンテンツ全体(subject/body_html_part/body_text_part)のサイズ は、150,000 byte以内で指定してください。 | コンテンツ全体サイズが上限を超過した |
10 | 400 | HTMLパートメール(body_html_part)は、100,000 byte以内で指定してください。 | 本文(HTMLパート)が100,000 byteを超過した |
11 | 400 | テキストパートメール(body_text_part)は 65,535文字以内で指定してください。 | 本文(テキストパート)が65535文字を超過した |
12 | 400 | memoは10000文字以内で指定してください。 | memoが10000文字を超過した |
13 | 400 | IF文挿入の中にIF文挿入を記述することはできません。 | IF文挿入がネストしている |
14 | 400 | 禁則文字(%%で囲まれた文字列)が含まれています。 禁則文字を削除してください。禁則文字とは、以下の正規表現で表される文字列を指します。%%[a-zA-Z0-9_]+%% | 禁則文字が含まれている |
15 | 400 | データ挿込やIF文挿込等の挿込の数は、150以内にしてください。 | 挿込数が上限を超過した |
16 | 400 | HTMLパートの本文には、bodyタグの開始タグと終了タグをそれぞれ1つだけ記述してください。 | 本文(HTMLパート)のbodyタグが開始と終了それぞれで1つでない |
17 | 400 | データ挿込や画像挿込等で指定したデータファイルやコンテンツが存在しません。 存在するデータファイルやコンテンツを指定してください。 | データファイルやコンテンツが存在しない |
18 | 400 | テキストパートで1行が800byteを超えています。 | 本文(テキストパート)で1行が800byteを超過した |
19 | 400 | HTMLパートで1つのタグが800byteを超えています。 | 本文(HTMLパート)で1つのタグが800byteを超過した |
20 | 400 | HTMLパートでタグ以外の部分で1行が800byteを超えています。 | 本文(HTMLパート)でタグ以外の部分で1行が800byteを超過した |
21 | 400 | custom_domain_name「{custom_domain_name}」が存在しません。存在するカスタムドメイン設定のドメイン(FQDN)を指定してください。 | URLを短縮URLにするかが「true」でカスタムドメイン設定が存在しない |
22 | 400 | custom_domain_name「{custom_domain_name}」のステータスが有効ではありません。 ステータスが有効のcustom_domain_nameを指定してください。 | URLを短縮URLにするかが「true」でカスタムドメイン設定のステータスが有効ではない |
23 | 400 | custom_domain_nameは255文字以内で指定してください。 | カスタムドメイン名が255文字を超過した |
【レスポンスボディサンプル(成功レスポンス(201))】
{
"result": {
"code": 201,
"contents_id": "12345",
"contents_name": "メールA",
"body_html_part": "<!DOCTYPE html>n<html>n<head>n<meta charset="utf-8">n</head>n<body>n<p>HTMLの本文です。</p><p><a href="https://short.domain/3XwHs01">リンク</a></p></body>n</html>",
"body_text_part": "XXX様nnテストメールnnhttps://short.domain/7PxGa02nnhttps://short.domain/3XwHs01",
"target_url_count": 2,
"shortened_url_count": 2,
"skipped_url_count": 0,
"short_url_contents": [
{
"id": "10001",
"name": "https://example.com/abc",
"short_url": "https://short.domain/3XwHs01",
"actual_url": "https://example.com/abc"
},
{
"id": "10002",
"name": "https://example.com/xyz",
"short_url": "https://short.domain/7PxGa02",
"actual_url": "https://example.com/xyz"
}
]
}
}