メール配信

KREISEL API を利用して、メール文面の作成から配信予約、配信状況の確認、結果の取得までの一連の操作を行う方法について説明します。

メール文面を作成する

API 経由でメール文面を作成するには、POST /api/v1/add_mail_message を使用します。

備考

KREISEL では、メール配信のプロセスを「メール文面作成」と「メール配信予約」の 2 つのステップに分けています。API でもこの考え方を踏襲しており、それぞれ別のエンドポイントを呼び出す必要があります。

リクエスト

リクエストボディには、文面を作成するデータベースの ID と、メール文面の詳細情報を含めます。

キー	データ型	必須	説明
`member_table_id`	Integer	○	データベースのIDを指定します。
`mail_info`	Object	○	メール文面の詳細情報を格納したオブジェクトを指定します。

`mail_info` オブジェクトの詳細

キー	データ型	必須	説明
`allow_hankana`	Boolean		`true`を指定すると、メール本文や件名などに半角カナが使用できます。デフォルトは`false`です。
`type`	Integer	○	メールの種別を数値で指定します。・`1`: テキストメール・`2`: HTMLメール・`3`: マルチパートメール
`from`	String	○	送信元メールアドレス。
`from_desc`	String		送信元名称。
`reply`	String		返信先メールアドレス。
`reply_desc`	String		返信先名称。
`subject`	String	○	メールの件名。
`text_part`	String	`type`に依存	テキストパートの本文。`type`が `1` または `3` の場合に必須です。
`html_part`	String	`type`に依存	HTMLパートの本文。`type`が `2` または `3` の場合に必須です。
`clickcounts`	Array		クリックカウントを取得したいURL情報の配列。詳細は仕様書を参照してください。
`open_clickcount`	Boolean		開封率クリックカウントを取得するかどうかを指定します（HTMLメール、マルチパートメールのみ有効）。

注意

API では、登録済みメールヘッダの呼び出しや S/MIME 署名の指定はできません。
文面作成時に確認メールは送信されません。

レスポンス

成功すると、作成されたメール文面の ID が返されます。

キー	データ型	説明
`message_id`	Integer	登録されたメール文面のID。

サンプルコード

テキストメールの作成

<?php

$apiUrl = 'https://krs.bz/<環境ID>/api/v1/add_mail_message';
$apiToken = 'YOUR_API_TOKEN'; // 取得したAPIトークンに置き換えてください

// メール文面情報
$mailInfo = [
    'allow_hankana' => false,
    'type' => 1, // テキストメール
    'from' => 'foo@example.com',
    'from_desc' => 'トライコーン',
    'reply' => 'foo_reply@example.com',
    'reply_desc' => 'トライコーン返信先',
    'subject' => '件名サンプル',
    'text_part' => 'このメールはテキストメールです。'
];

$params = [
    'member_table_id' => 1,
    'mail_info' => $mailInfo,
];

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiToken,
    'Content-Type: application/json',
]);

$response_body = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_code === 200) {
    $response = json_decode($response_body);
    echo '文面を登録しました。', PHP_EOL;
    echo 'メール文面ID : ', $response->message_id, PHP_EOL;
} else {
    echo 'APIリクエストに失敗しました。', PHP_EOL;
    echo 'HTTP Status: ', $http_code, PHP_EOL;
    echo 'Response: ', $response_body, PHP_EOL;
}

HTMLメールの作成

typeを2にし、html_partを指定します。

<?php

$apiUrl = 'https://krs.bz/<環境ID>/api/v1/add_mail_message';
$apiToken = 'YOUR_API_TOKEN'; // 取得したAPIトークンに置き換えてください

// メール文面情報
$mailInfo = [
    'allow_hankana' => false,
    'type' => 2, // HTMLメール
    'from' => 'foo@example.com',
    'from_desc' => 'トライコーン',
    'reply' => 'foo_reply@example.com',
    'reply_desc' => 'トライコーン返信先',
    'subject' => '件名サンプル',
    'html_part' => '<html><body>このメールはHTMLメールです</body></html>'
];

// 以下、cURL処理はテキストメールのサンプルと同様

メール配信を予約する

作成したメール文面を配信予約するには、POST /api/v1/add_delivery_schedule を使用します。この API はテキスト、HTML、マルチパートなど、すべてのメールタイプの配信予約に対応しています。

リクエスト

キー	データ型	必須	説明
`mail_message_id`	Integer	○	配信するメール文面のID。
`delivery_info`	Object	○	配信予約の詳細情報を格納したオブジェクト。

`delivery_info` オブジェクトの詳細

キー	データ型	必須	説明
`title`	String	○	配信予約の名称。管理画面の「配信履歴」に表示されます。
`condition_id`	Integer	○	配信対象を絞り込むための抽出条件ID。`1`を指定すると全員に配信します。
`element_id`	Integer	○	配信に使用するメールアドレス項目のID。
`delivery_date`	Integer	○	配信日時をUNIXタイムスタンプで指定します。

注意

API で配信予約を行う場合、確認メールは送信されません。

レスポンス

成功すると、登録された配信予約の ID が返されます。

キー	データ型	説明
`delivery_id`	Integer	登録された配信ID。

サンプルコード

テキストメールの文面を作成し、即時配信予約を行う例です。HTML メールやマルチパートメールも同様の手順で配信できます。

特定の会員だけに配信するには？

あらかじめ KREISEL の管理画面で、配信対象者を絞り込むための「抽出条件」を作成しておく必要があります。condition_idにその抽出条件の ID を指定することで、ターゲティング配信が可能です。

<?php

$apiUrlBase = 'https://krs.bz/<環境ID>/api/v1/';
$apiToken = 'YOUR_API_TOKEN'; // 取得したAPIトークンに置き換えてください

// 共通cURLオプション
$commonCurlOptions = [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
];

try {
    // 1. メール文面の作成
    $mailInfo = [
        'type' => 1, // テキストメール
        'from' => 'foo@example.com',
        'from_desc' => 'トライコーン',
        'subject' => '件名サンプル',
        'text_part' => 'このメールはテキストメールです。'
    ];
    $addMessageParams = [
        'member_table_id' => 1,
        'mail_info' => $mailInfo,
    ];

    $ch = curl_init($apiUrlBase . 'add_mail_message');
    curl_setopt_array($ch, $commonCurlOptions);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($addMessageParams));
    $response_body = curl_exec($ch);
    if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) {
        throw new Exception('メール文面作成失敗: ' . $response_body);
    }
    $mailMessageId = json_decode($response_body)->message_id;
    echo 'メール文面を作成しました。ID: ', $mailMessageId, PHP_EOL;
    curl_close($ch);

    // 2. 配信予約の作成
    // 実行時刻から直近の5分単位の時刻を計算
    $now = time();
    $deliveryTimestamp = $now + (300 - $now % 300);

    $deliveryInfo = [
        'title' => date('Y年m月d日 H時i分', $deliveryTimestamp) . '配信',
        'condition_id' => 1, // 全員に配信
        'element_id' => 7,   // メールアドレス項目のID
        'delivery_date' => $deliveryTimestamp
    ];

    // 特定の会員だけに配信する場合は、事前に作成した抽出条件のIDを指定します
    // 'condition_id' => 2,

    $addScheduleParams = [
        'mail_message_id' => $mailMessageId,
        'delivery_info' => $deliveryInfo,
    ];

    $ch = curl_init($apiUrlBase . 'add_delivery_schedule');
    curl_setopt_array($ch, $commonCurlOptions);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($addScheduleParams));
    $response_body = curl_exec($ch);
    if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) {
        throw new Exception('配信予約失敗: ' . $response_body);
    }
    $deliveryId = json_decode($response_body)->delivery_id;
    echo '配信予約を行いました。配信ID: ', $deliveryId, PHP_EOL;
    curl_close($ch);

} catch (Exception $e) {
    echo 'エラー: ', $e->getMessage(), PHP_EOL;
}

メールの配信状況を確認する

配信予約したメールの現在のステータスを確認するには POST /api/v1/get_delivery_status を使用します。

リクエスト

キー	データ型	必須	説明
`delivery_id`	Integer	○	状況を確認したい配信のID。

レスポンス

キー	データ型	説明
`phase`	Integer	配信フェーズを数値で返します。詳細は下表を参照。
`desc`	String	「引き渡し中」「引き渡し終了」フェーズの補足情報（例: 配信対象数 3054 （37%完了））。

`phase` の詳細

数値	名称	説明
`0`	配信予約中	配信予約がされている状態。配信処理はまだ行われていません。
`1`	配信リスト作成中	配信時刻になり、配信対象となる会員リストを作成している状態です。
`2`	引き渡し中	配信処理を実行している状態です。
`3`	引き渡し終了	配信処理が完了した状態です。

サンプルコード

配信予約を行い、配信処理が完了するまで 10 秒ごとにステータスを確認し続ける例です。

<?php

// ... (配信予約までの処理は前のサンプルを参照) ...
$deliveryId = 1; // 実際の配信IDに置き換えてください
$apiUrl = 'https://krs.bz/<環境ID>/api/v1/get_delivery_status';
$apiToken = 'YOUR_API_TOKEN';

$isFinish = false;
$currentPhase = -1;

while (!$isFinish) {
    $params = ['delivery_id' => $deliveryId];

    $ch = curl_init($apiUrl);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ]);

    $response_body = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($http_code !== 200) {
        echo 'APIエラー: ', $response_body, PHP_EOL;
        break;
    }

    $response = json_decode($response_body);
    $newPhase = $response->phase;

    if ($currentPhase !== $newPhase) {
        $currentPhase = $newPhase;
        switch ($currentPhase) {
            case 0:
                echo '配信予約中です', PHP_EOL;
                break;
            case 1:
                echo '配信リスト作成中です', PHP_EOL;
                break;
            case 2:
                echo '引き渡し中です (', $response->desc, ')', PHP_EOL;
                break;
            case 3:
                echo '配信処理が完了しました', PHP_EOL;
                $isFinish = true;
                break;
        }
    }
    if (!$isFinish) {
        sleep(10);
    }
}

メール配信結果を取得する

配信が完了したメールの結果（配信数やエラー数など）を取得するには POST /api/v1/get_delivery_result を使用します。

備考

この API は配信完了前にも呼び出し可能ですが、配信フェーズが「配信予約中」または「配信リスト作成中」の場合、count_info の各値はすべて 0 となります。

リクエスト

キー	データ型	必須	説明
`delivery_id`	Integer	○	結果を取得したい配信のID。

レスポンス

キー	データ型	説明
`count_info`	Object	種別ごとの配信数を格納したオブジェクト。
`start_date`	Integer	配信を開始した日時のUNIXタイムスタンプ。
`end_date`	Integer	配信の引き渡しが完了した日時のUNIXタイムスタンプ。

`count_info` オブジェクトの詳細

キー	データ型	説明
`all`	Integer	全配信対象数。
`stopped`	Integer	配信停止の対象数。
`no_address`	Integer	メールアドレスが空欄だった対象数。
`error`	Integer	配信エラーになった対象数。
`blacklist`	Integer	ブラックリストに該当した対象数。
`unsubscribed_address`	Integer	登録解除リストに該当した対象数。
`ready`	Integer	文面引き渡し待ちの対象数。
`composed`	Integer	文面引き渡しが完了した対象数。

サンプルコード

配信処理が完了したことを確認してから、配信結果を取得・表示する例です。

<?php

// ... (配信完了まで待機する処理は前のサンプルを参照) ...

$deliveryId = 1; // 実際の配信IDに置き換えてください
$apiUrl = 'https://krs.bz/<環境ID>/api/v1/get_delivery_result';
$apiToken = 'YOUR_API_TOKEN';

$params = ['delivery_id' => $deliveryId];

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiToken,
    'Content-Type: application/json',
]);

$response_body = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_code === 200) {
    $result = json_decode($response_body);
    $countInfo = $result->count_info;

    echo '配信が完了しました。', PHP_EOL;
    echo '配信開始日時: ', date('Y年m月d日 H時i分s秒', $result->start_date), PHP_EOL;
    echo '引き渡し完了日時: ', date('Y年m月d日 H時i分s秒', $result->end_date), PHP_EOL;
    echo '全配信対象レコード: ', $countInfo->all, PHP_EOL;
    echo '引き渡し成功レコード: ', $countInfo->composed, PHP_EOL;
    echo 'エラーレコード: ', $countInfo->error, PHP_EOL;
} else {
    echo 'APIエラー: ', $response_body, PHP_EOL;
}

メール文面を作成する​

リクエスト​

mail_info オブジェクトの詳細​

レスポンス​

サンプルコード​

テキストメールの作成​

HTMLメールの作成​

メール配信を予約する​

リクエスト​

delivery_info オブジェクトの詳細​

レスポンス​

サンプルコード​

メールの配信状況を確認する​

リクエスト​

レスポンス​

phase の詳細​

サンプルコード​

メール配信結果を取得する​

リクエスト​

レスポンス​

count_info オブジェクトの詳細​

サンプルコード​

メール文面を作成する

リクエスト

`mail_info` オブジェクトの詳細

レスポンス

サンプルコード

テキストメールの作成

HTMLメールの作成

メール配信を予約する

リクエスト

`delivery_info` オブジェクトの詳細

レスポンス

サンプルコード

メールの配信状況を確認する

リクエスト

レスポンス

`phase` の詳細

サンプルコード

メール配信結果を取得する

リクエスト

レスポンス

`count_info` オブジェクトの詳細

サンプルコード