メールコンテンツ新規作成APIを実装したい
回答
本記事では、貴社の基幹システム/アプリケーションからb→dash管理画面を介さずにメールコンテンツを新規作成できるAPIについて紹介しています。
APIの実装に向けて、大きく下記の3つの観点でご説明します。
1. メールコンテンツ新規作成APIの概要を確認する
2. 利用前提となる共通仕様と非機能要件を確認する
3. リクエスト/レスポンスの仕様に沿って実装する
各観点の詳細は、以下をご参照ください。
※ 本APIで作成したメールコンテンツをAPIから配信したい場合は、「メール配信設定新規作成APIを実装したい」をご参照ください
1. メールコンテンツ新規作成APIの概要を確認する
メールコンテンツ新規作成APIは、貴社の基幹システム/アプリケーションとb→dashを連携させることで、b→dash管理画面を介さずにメールコンテンツの新規作成ができるAPIです。
本APIで作成できるメールコンテンツ
b→dash管理画面の「メールコンテンツ新規作成画面」における操作と同様に、下記3種類のメールコンテンツを作成できます。
・HTML/テキストメール(マルチパート)
・HTMLメール
・テキストメール
テンプレート機能には対応していません
本APIでは「HTML/テキストメール(マルチパート)」「HTMLメール」のテンプレート機能を用いたメールコンテンツの作成はできませんのでご注意ください。
b→dash管理画面における各メール編集画面のイメージは、下記のとおりです。
※ 上記は「HTML/テキストメール(カスタマイズ・GUI編集モード)」「テキストメール」の編集画面例です
※ 上記は「HTML/テキストメール(カスタマイズ・HTML編集モード)」の編集画面例です
b→dash管理画面上での更新結果の確認方法
本APIを利用した結果は、b→dash管理画面の「メールコンテンツ一覧画面」および「メールコンテンツ詳細画面(更新履歴モーダル)」で確認することができます。
※ 上記は「メールコンテンツ一覧画面」の例です
※ 上記は「メールコンテンツ詳細画面(更新履歴モーダル)」の例です
2. 利用前提となる共通仕様と非機能要件を確認する
本APIを利用するにあたっての前提事項として、共通仕様と非機能要件を確認します。
共通仕様
メールコンテンツ新規作成APIでは、b→dash APIの共通仕様も参照する必要があります。共通仕様の詳細については「b→dash APIの共通仕様を知りたい」をご参照ください。
非機能要件
メールコンテンツ新規作成APIの非機能要件は、下記のとおりです。「全体サイズ上限」のみb→dash APIの共通仕様と異なるため、特にご注意ください。
# |
項目 |
非機能要件 |
1 |
URI長の上限 | 10KBまで(共通仕様同様) |
2 |
全体サイズ上限 | 1000kbまで |
3 |
レスポンス | リクエストからレスポンスの間は5秒以内(共通仕様同様) |
4 |
月間リクエスト上限数 | 10万リクエストまで ※ 超過した場合でも、エラーになりません(共通仕様同様) |
5 |
分間リクエスト上限数 | 100リクエストまで(共通仕様同様) |
6 |
レート制限 | 20秒あたり100リクエストまで(共通仕様同様) |
7 |
同時接続上限数 | 5リクエストまで(共通仕様同様) |
8 |
タイムアウト | 60秒まで(共通仕様同様) |
※ 上限数は、1アカウント内の上限とします
3. リクエスト/レスポンスの仕様に沿って実装する
メールコンテンツ新規作成APIの処理の流れと、リクエスト/レスポンスの仕様を説明します。
処理フロー図
メールコンテンツ新規作成APIの処理フロー図は、下記のとおりです。
メールコンテンツ新規作成リクエスト
下記の手順で、メールコンテンツ新規作成のリクエストを行います。
1. JSON形式のファイル(拡張子: .json)にリクエストボディパラメータを指定して、メールコンテンツの更新内容を送信するためのリクエストボディを準備します。
2. メールコンテンツ新規作成APIのURI、準備したリクエストボディ、リクエストヘッダパラメータを用いて、貴社Webアプリから「POST」リクエスト形式でメールコンテンツ新規作成のリクエストを送信します。
リクエストボディパラメータ
プロパティ |
型/サイズ |
必須 |
値 |
説明 |
| 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にする: 「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様\n\nテストメール\n\nhttps://example.com/xyz\n\nhttps://example.com/abc",
"memo": "メモ",
"is_shorten_url": true,
"custom_domain_name": "short.domain"
}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からレスポンスが返されます。
レスポンスボディパラメータ
パラメータ名 |
データ型 |
説明 |
| 階層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 |
【レスポンスボディサンプル(成功レスポンス: 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様\n\nテストメール\n\nhttps://short.domain/7PxGa02\n\nhttps://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"
}
]
}
}リクエストエラー発生時のエラーメッセージ一覧
リクエストエラー発生時に返されるエラーメッセージは、下記のとおりです。
エラーメッセージ詳細(23件)
# |
コード |
エラーメッセージ |
説明 |
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文字を超過した |