API概要

配信済タスク一覧の取得を行う

APIから送信されるXMLの書式は以下の通りとなります。

<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="urn:3hands:3mail">
  <status>OK</status>        //ステータス
  <code>202</code>           //コード
  <message>success</message> //メッセージ
  <task>
    <id>99</id>                           //タスクID
    <subject>テストメール1</subject>       //メールタイトル
    <start_at>2007-11-11 11:11</start_at> //配信開始日時
    <end_at>2007-11-11 11:22</end_at>     //配信終了日時
    <num>100</num>                        //配信数
    <num_sent>92</num_sent>                   //暫定有効配信数
    <num_bounced>8</num_bounced>                //暫定無効配信数
  </task>
  <task>
    (taskの数だけ繰り返し)
  </task>
</response>


配信済のタスクが0の場合でもstatusはOKとなります。
num(配信数)は、配信したアドレスの件数です。
num_bounced(暫定無効配信数)は、何らかの理由で宛先に届かなかった件数です。リターンメール自動集計機能をつかっていた場合に集計されます。メールが届かなかった場合、一般的に数日以内にリターンメールが戻り、無効件数としてカウントされます。そのためこの数字は配信後徐々に増加します。
num_sent(暫定有効配信数)は、配信数から暫定無効配信数を除いたものです。

サンプルスクリプト

<?php

//APIへ送信するデータ
$post_data = array(
    "login_id" => "login@example.com", //ログインID
    "password" => "password"           //ログインパスワード
);
   
//APIのHostを設定
$api_host = "example.com";
   
//APIのPathを設定
$api_path = "/API/history";

//APIへ接続
$sp = fsockopen('ssl://' . $api_host, 443, $errno, $errstr, 30);
   
//エラーチェック
if(!$sp){
    print $errno . "<br>" . $errstr;
    exit;
}

//boundary生成
$boundary = "-----" . md5(uniqid());
   
//header生成
$header  = "POST " . $api_path . " HTTP/1.0\r\n";
$header .= "Host: " . $api_host . "\r\n";
$header .= "Content-type: multipart/form-data, boundary=" . $boundary . "\r\n";
$header .= "Referer: http://" . $_SERVER['SERVER_NAME'] . $_SERVER['SCRIPT_NAME'] . "\r\n";
$header .= "Accept: */*\r\n";
   
//body生成
$body = "";
   
//テキストデータをAPIへ送信できるように変換
foreach ($post_data as $key => $val){
    $body .= "--" . $boundary . "\r\n";
    $body .= "Content-Disposition: form-data; name=\"" . $key . "\"\r\n";
    $body .= "\r\n" . $val . "\r\n";
    $body .= "--" . $boundary . "\r\n";
}
   
//送信データ末尾の区切り文字を追加
$body .= "--" . $boundary . "--\r\n";
$body .= "\r\n\r\n";
   
//ヘッダーにbodyのサイズを追加
$header .= "Content-length: " . strlen($body) . "\r\n\r\n";

//データ送信
fputs($sp, $header);
fputs($sp, $body);

//データ受信
$buf = "";
$response = fgets($sp);
   
if (substr_count($response, "200 OK") > 0){
    while (!feof($sp)){
        $buf = $buf . fread($sp, 4096);
    }
}else{
    print "データ受信に失敗しました";
    exit;
}
   
//接続終了
fclose($sp);

//結果XMLを取得
$result = substr($buf, strpos($buf, "\r\n\r\n")+4);

//XMLをパースする
$result_xml = simplexml_load_string($result);

//結果を取得し表示
print "status:" . $result_xml->status . "<br>";   //ステータス
print "code_no:" . $result_xml->code_no . "<br>"; //コード
print "message:" . $result_xml->message . "<br>"; //メッセージ

//タスクの詳細を取得し表示
foreach ($result_xml as $task){
    print "----------" . "<br>";
    print "taskid:" . $task->id . "<br>";         //タスクID
    print "subject:" . $task->subject . "<br>";   //メールタイトル
    print "start_at:" . $task->start_at . "<br>"; //配信開始日時
    print "end_at:" . $task->end_at . "<br>";     //配信終了日時
    print "num:" . $task->num . "<br>";           //配信数
    print "num_sent:" . $task->num_sent . "<br>";           //暫定有効配信数
    print "num_bounced:" . $task->num_bounced . "<br>";           //暫定無効配信数

}

exit;

?>

サンプルスクリプト解説

APIへ送信するデータ及び、APIのURLについて設定を行います。

//APIへ送信するデータ
$post_data = array(
    "login_id" => "login@example.com", //ログインID
    "password" => "password"           //ログインパスワード
);
   
//APIのHostを設定
$api_host = "example.com";
   
//APIのPathを設定
$api_path = "/API/history";

APIへソケットを使って接続を行います。

//APIへ接続
$sp = fsockopen('ssl://' . $api_host, 443, $errno, $errstr, 30);
   
//エラーチェック
if(!$sp){
    print $errno . "<br>" . $errstr;
    exit;
}

APIへ送信するデータの作成を行います。

//boundary生成
$boundary = "-----" . md5(uniqid());
   
//header生成
$header  = "POST " . $api_path . " HTTP/1.0\r\n";
$header .= "Host: " . $api_host . "\r\n";
$header .= "Content-type: multipart/form-data, boundary=" . $boundary . "\r\n";
$header .= "Referer: http://" . $_SERVER['SERVER_NAME'] . $_SERVER['SCRIPT_NAME'] . "\r\n";
$header .= "Accept: */*\r\n";
   
//body生成
$body = "";
   
//テキストデータをAPIへ送信できるように変換
foreach ($post_data as $key => $val){
    $body .= "--" . $boundary . "\r\n";
    $body .= "Content-Disposition: form-data; name=\"" . $key . "\"\r\n";
    $body .= "\r\n" . $val . "\r\n";
    $body .= "--" . $boundary . "\r\n";
}
   
//送信データ末尾の区切り文字を追加
$body .= "--" . $boundary . "--\r\n";
$body .= "\r\n\r\n";
   
//ヘッダーにbodyのサイズを追加
$header .= "Content-length: " . strlen($body) . "\r\n\r\n";

APIへデータの送信を行います。

//データ送信
fputs($sp, $header);
fputs($sp, $body);

データの受信を行います。

ヘッダーが "200 OK" 以外の場合はエラーとなります。

//データ受信
$buf = "";
$response = fgets($sp);
   
if (substr_count($response, "200 OK") > 0){
    while (!feof($sp)){
        $buf = $buf . fread($sp, 4096);
    }
}else{
    print "データ受信に失敗しました";
    exit;
}
   
//接続終了
fclose($sp);

受信したデータからXML部分のみを取得後パースを行います。

//結果XMLを取得
$result = substr($buf, strpos($buf, "\r\n\r\n")+4);

//XMLをパースする
$result_xml = simplexml_load_string($result);

結果の基本項目は以下の方法で取得できます。

今回はサンプルなので取得結果をそのまま表示します。

//結果を取得し表示
print "status:"  . $result_xml->status  . "<br>"; //ステータス
print "code:"    . $result_xml->code    . "<br>"; //コード
print "message:" . $result_xml->message . "<br>"; //メッセージ

タスクの詳細データは以下の方法で取得できます。

詳細はステータスがOK(送信した内容に問題が無い)の場合のみ取得できます。

//タスクの詳細を取得し表示
foreach ($result_xml as $task){
    print "----------" . "<br>";
    print "taskid:" . $task->id . "<br>";         //タスクID
    print "subject:" . $task->subject . "<br>";   //メールタイトル
    print "start_at:" . $task->start_at . "<br>"; //配信開始日時
    print "end_at:" . $task->end_at . "<br>";     //配信終了日時
    print "num:" . $task->num . "<br>";           //配信数
    print "num_sent:" . $task->num_sent . "<br>";           //暫定有効配信数
    print "num_bounced:" . $task->num_bounced . "<br>";           //暫定無効配信数
}

サンプルスクリプトの実行結果は以下の通りとなります。

status:OK
code:202
message:success
----------
taskid:100
subject:メールサンプル1
start_at:2007-11-22 15:30:00
end_at:2007-11-22 16:00:00
num:100
num_sent:92
num_bounced:8
----------
taskid:99
subject:メールサンプル2
start_at:2007-10-22 12:00:00
end_at:2007-10-22 16:00:00
num:1000
num_sent:953
num_bounced:47

スクリプト実行後の処理について

実際にはXMLを取得後、ステータス及びコードに合わせて処理を行ってください。(正常終了、エラー表示等)

前のページへ戻る