メールコンテンツ新規作成APIを実装したい

メールコンテンツ新規作成APIとは

本APIの概要

メールコンテンツ新規作成APIとは、貴社の基幹システム/アプリケーションとb→dashを繋ぐことでb→dash管理画面を介さずにメールアプリの機能の1つであるメールコンテンツの新規作成をすることができるAPIです

貴社の基幹システム/アプリケーションに連携したメールコンテンツの作成を行いたい場合は、本API仕様書をご参照のもと貴社開発環境に実装してください。

本APIで作成したメールコンテンツを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の仕様

処理フロー図

メールコンテンツ新規作成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" 
      } 
    ]
  } 
}