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を取得後、ステータス及びコードに合わせて処理を行ってください。(正常終了、エラー表示等)
