ホーム > スリーメール > API

API概要

タスク詳細の取得を行う

タスク詳細の取得を行います。取得項目は、

  • メールタイトル
  • メール本文
  • Fromアドレス
  • Fromテキスト
  • Return-Path
  • Reply-To
  • 配信開始日時

となります。

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

リクエストパラメータ
パラメータ名 データタイプ 必須 説明
login_id string ○ ログイン用ID
password string ○ ログイン用パスワード
id int ○ タスクID

APIからのXMLについて

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

<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="urn:3hands:3mail">
  <status>OK</status>                                 //ステータス
  <code>204</code>                                    //コード
  <message>success</message>                          //メッセージ
  <subject>メールタイトル</subject>                     //メールタイトル
  <from_address>test_addr@example.com</from_address>  //Fromアドレス
  <from_txt>テストアドレス</from_txt>                   //Fromテキスト
  <body>メール本文</body>                              //メール本文
  <return_path>return_addr@example.com</return_path>  //リターンパス
  <reply_to>return_addr@example.com</reply_to>        //Reply-To
  <start_at>2007-11-22 11:11</start_at>               //配信日時
  <task_status>WAIT</task_status>  //タスクの状態(WAIT:配信待ち、READY:配信中、DONE:配信終了)
  <num>100</num>                        //配信数
  <num_sent>92</num_sent>                   //暫定有効配信数
  <num_bounced>8</num_bounced>                //暫定無効配信数
</response>


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

サンプルスクリプト

<?php

//APIへ送信するデータ
//$_REQUESTの部分については、可能であれば$_POSTか$_GETを指定してください
//今回はサンプルの為、汎用性を考えて$_REQUESTとします
$post_data = array(
    "login_id" => "login@example.com", //ログインID
    "password" => "password",          //ログインパスワード
    "id" => $_REQUEST['id']            //タスクID
);
   
//APIのhostを設定
$api_host = "example.com";
   
//APIのpathを設定
$api_path = "/API/get_task";

//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";
   
//ヘッダーにデータ部のサイズを追加
$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);

//XMLのデータを取得
print "status:"       . $result_xml->status;       //ステータス
print "code:"         . $result_xml->code;         //コード
print "message:"      . $result_xml->message;      //メッセージ
print "subject:"      . $result_xml->subject;      //メールタイトル
print "from_address:" . $result_xml->from_address; //Fromアドレス
print "from_text"     . $result_xml->from_text;    //Fromテキスト
print "from_body"     . $result_xml->body;         //メール本文
print "return_path"   . $result_xml->return_path;  //リターンパス
print "reply_to"      . $result_xml->reply_to;     //Reply-To
print "start_at"      . $result_xml->start_at;     //配信日時
print "task_status"   . $result_xml->task_status;  //タスク状態
print "num:" . $task->num;           //配信数
print "num_sent:" . $task->num_sent;           //暫定有効配信数
print "num_bounced:" . $task->num_bounced;           //暫定無効配信数

exit;

?>

サンプルスクリプト解説

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

//APIへ送信するデータ
//$_REQUESTの部分については、可能であれば$_POSTか$_GETを指定してください
//今回はサンプルの為、汎用性を考えて$_REQUESTとします
$post_data = array(
    "login_id" => "login@example.com", //ログインID
    "password" => "password",          //ログインパスワード
    "id" => $_REQUEST['id']            //タスクID
);
   
//APIのhostを設定
$api_host = "example.com";
   
//APIのpathを設定
$api_path = "/API/get_task";

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";
   
//ヘッダーにデータ部のサイズを追加
$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);

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

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

//XMLのデータを取得
print "status:"       . $result_xml->status;       //ステータス
print "code:"         . $result_xml->code;         //コード
print "message:"      . $result_xml->message;      //メッセージ
print "subject:"      . $result_xml->subject;      //メールタイトル
print "from_address:" . $result_xml->from_address; //Fromアドレス
print "from_text"     . $result_xml->from_text;    //Fromテキスト
print "from_body"     . $result_xml->body;         //メール本文
print "return_path"   . $result_xml->return_path;  //リターンパス
print "reply_to"      . $result_xml->reply_to;     //Reply-To
print "start_at"      . $result_xml->start_at;     //配信日時
print "task_status"   . $result_xml->task_status;  //タスク状態
print "num:" . $task->num;           //配信数
print "num_sent:" . $task->num_sent;           //暫定有効配信数
print "num_bounced:" . $task->num_bounced;           //暫定無効配信数

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

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

前のページへ戻る

特長 | 機能 | 事例 | 料金 | FAQ | 利用規約 | マニュアル | API | オンライン申込 | パンフレットのダウンロード
online-order
3HANDS Information お問い合わせはこちら