スリーメール｜スリーハンズ株式会社

API概要

クリックカウントの結果を取得

特定の配信タスクで、URLのクリックカウントを利用していた場合に、その結果を取得します。取得項目は次の通りです。

URLごとに

URLのID
URL
ユニーククリック数

クリック1件ごとに(※リクエストパラメータのincludes_logが1の場合)

URLのID
クリックしたユーザーのメールアドレスは、アップロードされたリストの何行目か
クリックした日時

リクエストURL
https://example.com/API/get_clicks
※正式なURLは御契約後にご連絡致します。

リクエストパラメータ

パラメータ名	データタイプ	必須	説明
login_id	string	○	ログイン用ID
password	string	○	ログイン用パスワード
id	string	○	タスクID
includes_log	string	○	クリック1件ごとのデータを含むか(含む = 1、デフォルト = 0)

APIからのXMLについて

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

<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="urn:3hands:3mail">
  <status>OK</status>                        //ステータス
  <code>211</code>                           //コード
  <message>success</message>                           //メッセージ
  <url>
    <id>1</id>       //URLのID
    <url>http://example.com/</url> //URL
    <count>1234</count> //ユニーククリック数
    <rate>34</rate> //開封率
  </url>
  <url>
    <id>2</id>       //URLのID
    <url>http://example.com/test.html</url> //URL
    <count>567</count> //ユニーククリック数
    <rate>21</rate> //開封率
  </url>
  <url>
    (URLの数だけ繰り返し)
  </url>
  //以下は includes_log が 1の場合のみ含まれます
  <click>
    <url_id>1</url>       //URLのID
    <line>123</line> //アドレスの行番号
    <created_at>2014-01-02 03:04:05</created_at> //クリックした日時
  </click>
  <click>
    <url_id>2</url>       //URLのID
    <line>345</line> //アドレスの行番号
    <created_at>2014-03-04 05:06:07</created_at> //クリックした日時
  </click>
  <click>
    (クリックの数だけ繰り返し)
  </click>
</response>

※クリックが0件の場合でもstatusはOKとなります。

返り値の詳細

名前	データタイプ	最大バイト数	説明
status	string	2	ステータス(OK=成功、NG=失敗)
code	string	3	コード(一覧)
message	string	255	メッセージ
url.id	int	11	ID
url.url	string	1023	URL
url.count	int	11	ユニーククリック数
url.rate	int	2	クリック率(%) (=ユニーククリック数/有効送信数)
click.url	string	1023	URL
click.line	int	11	クリックしたユーザーのメールアドレスは、アップロードされたリストの何行目か
click.created_at	string	32	クリック日時

サンプルスクリプト

<?php

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

//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:" . $result_xml->code . "<br>"; //コード
print "message:" . $result_xml->message . "<br>"; //メッセージ

//URLごとの集計結果を表示
foreach ($result_xml->url as $url){
    print "----------" . "<br>";
    print "id:" . $click->id . "<br>";    //URLのID
    print "url:" . $click->url. "<br>"; //URL
    print "count:" . $click->count. "<br>"; //ユニーククリック数
    print "rate:" . $click->rate. "<br>"; //クリック率
}

//クリック毎の詳細を取得し表示
foreach ($result_xml->click as $click){
    print "----------" . "<br>";
    print "URL:" . $click->url . "<br>";    //URL
    print "line:" . $click->line. "<br>"; //アドレスの行番号
    print "created_at:" . $click->created_at. "<br>"; //クリック日時
}

exit;

?>

サンプルスクリプト解説

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

//APIへ送信するデータ
$post_data = array(
    "login_id" => "login@example.com", //ログインID
    "password" => "password",          //ログインパスワード
    "id" => "90"                       //タスクID

);
   
//APIのHostを設定
$api_host = "example.com";
   
//APIのPathを設定
$api_path = "/API/get_clicks";

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(送信した内容に問題が無い)の場合のみ取得できます。

//URLごとの集計結果を表示
foreach ($result_xml->url as $url){
    print "----------" . "<br>";
    print "id:" . $click->id . "<br>";    //URLのID
    print "url:" . $click->url. "<br>"; //URL
    print "count:" . $click->count. "<br>"; //ユニーククリック数
    print "rate:" . $click->rate. "<br>"; //クリック率
}

//エラーの詳細を取得し表示
foreach ($result_xml->click as $click){
    print "----------" . "<br>";
    print "URL:" . $click->url . "<br>";    //URL
    print "line:" . $click->line. "<br>"; //アドレスの行番号
    print "created_at:" . $click->created_at. "<br>"; //クリック日時
}

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

status:OK
code:211
message:success
----------
id:1
url:http://example.com/
count:123
rate:21
----------
id:2
url:http://example.com/test.html
count:456
rate:33
----------
URL:1
line:1111
created_at:2014-01-02 03:04:05
----------
URL:2
line:1234
created_at:2014-05-06 07:08:09

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

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

注意事項

クリック履歴は配信から3ヶ月間のみ保存しています。それ以降は削除されますのでご注意ください。