メール配信API

配信予約API

必要項目を設定し、配信の予約および即時配信指示をおこないます。

キューイングモード

リクエストサイズが25KByteを超えた場合、リクエストをキューに保存し、非同期処理するモードで動作します。

キューイングモードとは

接続方法

認証

キューイングモード配信をご利用いただく場合、認証情報をHTTPヘッダに設定します。

送信方向 設定項目  設定値  内容
リクエスト X-AutomailUser ユーザーID mail/auth/nameタグに設定するユーザーIDと同様の値を指定します。
配信でエラーになった際、メール通知をおこなう宛先となるため、管理画面の「管理者機能タブ > ユーザアカウント管理」よりアカウントにメールアドレスを登録してご利用ください。
X-AutomailPassword パスワード mail/auth/passタグに設定するパスワードと同様の値を指定します。
X-AutomailUseSite サイトID mail/auth/siteタグに設定するサイトIDと同様の値を指定します。
X-AutomailUseService サービスID mail/auth/serviceタグに設定するサービスIDと同様の値を指定します。
X-AutomailUseRequestId リクエストID mail/delivery/request_idタグに設定するリクエストIDと同様の値を指定します。
ご注意
キューイングモード配信は、XML内に記載された認証情報および、リクエストIDは参照しません。必ずヘッダ情報に指定いただきますようお願いいたします。

リクエスト

ボディパラメーター

XML形式で設定します。

項目 データ型 必須 説明
mail データなし ◯ ルート要素であり、API v1で使用するXMLをまとめる唯一の要素

リクエスト時に認証情報を定義する方法については以下をご参照ください。

auth要素(共通)
delivery データなし ◯ 配信データに関する要素
詳細説明は以下をご参照ください。
delivery要素(共通)
delivery要素 (配信予約_リクエスト)
action 文字列 ◯ reserveを指定
setting データなし 〇 配信に関する設定を行う要素
詳細説明は以下をご参照ください。
setting(配信予約)
send_date 文字列 〇 配信時刻を指定
from_name 文字列(CDATA) 配信時に表示名に表示されるfrom名を指定
from 文字列 配信時に表示されるHeader Fromアドレスを指定
envelope_from 文字列 Envelope Fromアドレスを指定
option データなし 配信オプションの要素
詳細説明は以下をご参照ください。
option要素(配信予約)
stop_time 文字列 配信禁止時間帯（配信停止時刻）を指定
start_time 文字列 配信禁止時間帯（配信再開時刻）を指定
lifetim 文字列 メール生存時間を指定
retry_interval 数値 リトライ間隔を指定
throttle 数値 1分間あたりにメールを送信する通数を指定
s_mime データなし S/MIME利用を指定
opened_flag データなし 開封確認機能の利用を指定
contents 数値 〇 配信データを定義する要素
詳細説明は以下をご参照ください。
contents要素(配信予約)
image データなし 共通差込画像URLを指定
text 文字列(CDATA) 共通差込文言を指定
attach_file 文字列 添付したいファイルのURLを指定
subject 文字列(CDATA) △ メールの件名を指定
設定可能なサイズは500Byte以下となります。
body 文字列(CDATA) △ メールの本文を指定
templete データなし △ テンプレートを使用して配信する要素
send_list データなし ◯ 配信対象者を定義する要素
詳細説明は以下をご参照ください。
send_list要素(配信予約)
data データなし △ 配信先の情報を指定する要素
data要素(配信予約)
adress 文字列 △ 送信先のメールアドレスを指定
int_txt 文字列(CDATA) 個別の差込用データを指定
ext_txt データなし 要素textで指定された共通の差込用データを指定
ext_img データなし 要素imageで指定された共通の差込用データを指定
key_field 文字列(CDATA) 配信先ごとに取得したい情報を指定
unsubscribe_url 文字列 ワンクリック登録解除機能で配信先ごとに設定するURL
ご注意
差し込みは、メール本文に、名前やURLパラメーターなどの文字列を差し込みます。
設定可能な差し込み数は、文字列差し込みと画像差し込み合わせて255個までです。
差し込む文字数が多い場合、配信予約処理に時間がかかります。差し込み文字列はできる限り削減することを推奨します。

レスポンス

ボディパラメーター

項目 データ型 必須 説明
mail データなし ◯
result 文字列 △ 全体ステータス（認証エラー時などAPI個別処理前にエラーが発生した場合に出力）
※resultまたはerrors・deliveryのどれかが必須
errors データなし △ エラー（認証エラー時などAPI個別処理前にエラーが発生した場合に出力）
※resultまたはerrors・deliveryのどれかが必須
error 文字列 ● エラーメッセージ（認証エラー時などAPI個別処理前にエラーが発生した場合に出力）
delivery データなし △ 配信データ処理結果
※resultまたはerrors・deliveryのどれかが必須
delivery要素 (配信予約_レスポンス)
delivery要素(共通)
host_name 文字列 HOST名を返却する設定がある場合に返却
deliver_id 文字列 ● 配信ID
request_id 文字列 リクエストID
exec_cnt 文字列 ● メール処理数（成功数）
result 文字列 ● 全体ステータス
errors データなし エラー
error 文字列 エラーメッセージ
補足説明

  • 必須欄に「〇」がついている項目は必須項目であり、「△」がついている項目は同じレベルで下に続く項目のうちどれか1つが必須項目となります。
  • 「●」は親要素が選択されているときは必須項目となります。

サンプル

リクエスト

  • action～settingまで
<?xml version="1.0" encoding="UTF-8" ?>
<mail>
  <delivery id="0">
    <action>reserve</action><!-- メール配信API呼び出し指定 -->
    <request_id>xxxxxxxxxxxxxxxxxxxxxxxxxxxx</request_id><!--　重複配信抑止リクエストID -->
    <!-- メール送信時の設定 -->
    <setting>
      <send_date>now</send_date><!-- 送信日時指定 -->
      <from_name><![CDATA[XXXXXXX]]></from_name><!-- from名に表示される文言 -->
      <from>xxx@xx.jp</from><!-- Header Fromアドレスとして表示されるメールアドレス -->
      <envelope_from>xxx@xx.jp</envelope_from>
      <!-- 配信オプション -->
      <option>
        <stop_time>HHMI</stop_time><!-- 配信禁止時間帯指定（配信停止時刻） -->
        <start_time>HHMI</start_time><!-- 配信禁止時間帯指定（配信再開時刻） -->
        <lifetime>0000</lifetime><!-- 配信データの生存時間(秒) -->
        <retry_interval>0000</retry_interval><!-- リトライ実施時の、リトライ間隔(秒) -->
      </option>
      <throttle>0000</throttle><!-- 配信速度指定（通数/分） -->
      <s_mime use="0"/><!—S/MIME利用指定 -->
      <opened_flag use="0"/><!—開封確認利用指定 -->
    </setting>
    <contents>
      省略
    </contents>
    <send_list>
      省略
    </send_list>
  </delivery>
</mail>
  • contents要素subjectと要素bodyを使用
<?xml version="1.0" encoding="UTF-8" ?> 
<mail>
  <delivery id="0">
    <action>reserve</action>
    省略
    <!-- 配信メール内容 -->
    <contents>
      <image id="1">http://xxxxxxxx/xxxx.gif</image><!-- 共通差込画像。複数指定可。 -->
      <text id="1"><![CDATA[ユーザー共通文字列]]></text><!-- 共通差込文言。複数指定可。 -->
      <attach_file>http://xxxxxxxx/xxxx.pdf</attach_file><!-- 添付ファイル。複数指定可。-->
      <subject><![CDATA[サンプルメルマガ]]></subject><!-- メールの件名 -->
      <!-- メール本文（テキストパート） -->
      <!-- HTMLメール配信時には、HTMLメールの受信不可端末や、HTMLメール受信拒否端末向けに、テキストパートの指定が必須となります。 -->
      <body part="text">
        <!-- ##ext_txt_1##が共通差込文言の差込場所です。 -->
        <![CDATA[##ext_txt_1## テキストメール本文です。]]>
      </body> 
      <!-- メール本文（HTMLパート） -->
        <body part="html">
        <!-- htmlフォーマットでメール本文を作成します。 -->
        <![CDATA[
          <html>
            <head></head>
            <body>
              ##ext_txt_1##　htmlメール本文です。
              <img src="##ext_img_1##"><!-- 共通差込画像に指定しているURLで置き換わります-->
            </body>
          </html>
        ]]>
      </body>
    </contents>
    <send_list>
      省略
    </send_list>
  </delivery>
</mail>

要素contentsは、テンプレートを使用するかどうかで、構成要素が異なります。

  • contents要素templateを使用
<?xml version="1.0" encoding="UTF-8" ?>
<mail>
  <delivery id="x">
    <action>reserve</action>
      省略
    <contents>
      <!-- 共通差込や、要素send_listで指定する差込文言等も、テンプレート利用時に使用可能 -->
      <image id="1">http://xxxxxxxx/xxxx.gif</image>
      <text id="1"><![CDATA[ユーザー共通文字列]]></text>
      <template id="0"/><!-- テンプレートIDを指定 -->
    </contents>
    <send_list>
      省略
    </send_list>
  </delivery>
</mail>
  • send_list要素dataを使用
<?xml version="1.0" encoding="UTF-8" ?>
<mail>
  <delivery id="x">
    <action>reserve</action> 
    <contents>
      省略
    </contents>
    <!-- 送信対象指定 -->
    <send_list>
    <!-- XML内に指定する場合はdataを使用する -->
      <data id="1">
        <address device="3">xxxx@xxx.jp</address><!-- メール配信先アドレス -->
        <int_txt id="1">XXXXXX</int_txt><!-- 個別差込情報の指定 -->
        <ext_txt id="0">0</ext_txt><!-- 共通差込文言の指定 -->
        <ext_img id="0">0</ext_img><!-- 共通差込画像の指定 -->
        <key_field>XXXXXXXXX</key_field><!-- 補足情報を設定する場合に指定する。 -->
      </data>
    </send_list>
  </delivery>
</mail>

要素dataと要素ext_dataで、使用する要素が異なります。

  • send_list要素ext_dataを使用
<?xml version="1.0" encoding="UTF-8" ?>
<mail>
  <delivery id="x">
    <action>reserve</action>
    <contents>
      省略
    </contents>
    <!-- 送信対象指定 -->
    <send_list>
      <!-- データベースを使用する場合はext_dataを使用。 -->
      <ext_data type="user_table"><!-- 属性typeはデータベース指定のみ -->
        <list_id>0</list_id><!-- 複数リストオプション利用時、使用リスト指定 -->
        <query><![CDATA[属性名=XXX]]></query><!-- 配信対象の抽出条件 -->
        <extract_timing>delivery</extract_timing><!-- 配信データの作成契機 -->
      </ext_data>
    </send_list>
  </delivery>
</mail>

レスポンス

  • リクエストが25KByte以下の場合
<?xml version="1.0" encoding="UTF-8"?>
<mail>
  <delivery id="0">
    <host_name>xxxxxxxxxxxx</host_name>
    <deliver_id>xxxxxx</deliver_id>
    <request_id>xxxxxxxxxxxxxx</request_id>場合に付与 -->
    <exec_cnt>0</exec_cnt><"-- 実際に配信を行った件数。 -->
    <result code="0">エラーメッセージ</result>
    <!-- 処理エラー時に、以下の情報が付与される -->
    <errors>
      <error kind="xxxxxxxx" code="0000">エラーメッセージ</error>
    </errors >
  </delivery>
</mail>
  • リクエストが25KByteを超えた時の場合（deliveryタグなし）
<?xml version="1.0" encoding="UTF-8"?>
<mail>
  <deliver_id>xxxxxx</deliver_id>
  <request_id>xxxxxxxxxxxxxx</request_id>
  <exec_cnt>0</exec_cnt>
  <result code="0">エラーメッセージ</result>
  <errors>
    <error kind="xxxxxxxx" code="0000">エラーメッセージ</error>
  </errors>
</mail>