SERVICE

すべての情報の登録を行う

スリーメールAPI詳細

スリーメールAPI概要

メール配信に必要なすべての情報をAPI経由で登録します。

リクエストURL

https://example.com/API/set
※正式なURLはご契約後にお知らせします。

リクエストパラメータ

パラメータ名	データタイプ	必須	説明
login_id	string	○	ログイン用ID
password	string	○	ログイン用パスワード
file	file	○	配信リスト(gzipで圧縮した物)
subject	string	○	メールタイトル
body	string	○	メール本文
from_address	string	○	Fromアドレス
from_txt	string		Fromテキスト
returnpath	string		返信先メールアドレス(エラー時)
return_limit	int		許可するリターン回数の上限（1から3まで：省略時=3）
auto_return	int		自動リターン集計について　(利用する = 1)
replyto	string		返信先メールアドレス
file_to_attach	file		メール添付ファイル ※1つまで添付可能です
start_sending	string	○	メール配信開始日時について　(すぐに配信 = now　日時指定 = at)
year	int		メール配信開始時間(年)
month	int		メール配信開始時間(月)
day	int		メール配信開始時間(日)
hour	int		メール配信開始時間(時)
min	int		メール配信開始時間(分)
click_count	int		クリックカウント集計について（利用する = 1）
notify_disposition	int		開封率集計について（利用する = 1）
disposition_method	string		開封率の集計方法（開封通知ヘッダーを利用する = header、HTMLメールを利用する = html）
ignore_encoding	int		配信リストの文字コードチェックをしない（チェックをしない = 1）
use_utf8	int		配信時の文字コードにUTF-8を使う（使う = 1）詳細はUTF-8での配信を参照。
block_replace	int		ブロック差し込み機能を使う（使う = 1）詳細はブロック差し込み機能を参照。
dkim	int		DKIM署名を使う（使う = 1）
dkim_privkey	file		DKIM秘密鍵ファイル。鍵長は2048bit、ハッシュアルゴリズムは SHA-256 を使用してください。また、文字列ではなくファイルとしてアップロードしてください。
dkim_selector	string		DKIMのセレクタ
ocu	int		ワンクリック解除（One-Click Unsubscribe）ヘッダを使う（使う = 1）詳細はワンクリック解除を参照。
ocu_method	string		ワンクリック解除の方法（HTTPSを利用する＝ https、メールを利用する = mail）
ocu_url	string		ワンクリック解除にHTTPS を利用する場合、解除用のURL URL中に $1 や $2 等と記述した場合、該当の箇所が宛先CSVの2カラムめ、3カラムめ等に置き換えられた後、URLエスケープが行われます。例：宛先CSV を test1@example.com,12345 ocu_url を https://example.com/unsubscribe/$1 とした場合、 test1@example.com 宛てのメールのワンクリック解除用URLは https://example.com/unsubscribe/12345 となります。
ocu_mail_to	string		ワンクリック解除にメールを利用する場合、解除用の宛先メールアドレス
ocu_mail_subject	string		ワンクリック解除にメールを利用する場合、解除用メールの件名件名中に $1 や $2 等と記述した場合、該当の箇所が宛先CSVの2カラムめ、3カラムめ等に置き換えられた後、URLエスケープが行われます。例：宛先CSV を test1@example.com,12345 ocu_mail_subject を id=$1 とした場合、 test1@example.com 宛てのメールのワンクリック解除用メールの件名は id=12345 となります。

※year,month,day,hour,minはメール配信日時を指定する場合必須となります。

APIからのXMLについて

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

<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="urn:3hands:3mail">
  <status>OK</status>                      //ステータス
  <code>200</code>                         //コード
  <message>本登録に成功しました</message>    //メッセージ
  <valid>123</valid>                     　//有効件数
  <error>45</error>                      　//無効件数
  <task_id>67</task_id>                  　//配信タスクID
</response>

返り値の詳細

名前	データタイプ	最大バイト数	説明
status	string	2	ステータス(OK=成功、NG=失敗)
code	string	3	コード(一覧)
message	string	255	メッセージ
valid	int	11	有効件数
error	int	11	無効件数
task_id	int	11	配信タスクID

サンプルスクリプト

<?php
 
//APIへ送信するデータ
//$_REQUESTの部分については、可能であれば$_POSTか$_GETを指定してください
//今回はサンプルの為、汎用性を考えて$_REQUESTとします
$post_data = array(
    "login_id" => "login@example.com",             //ログインID
    "password" => "password",                      //ログインパスワード
    "subject" => $_REQUEST['subject'],             //メールタイトル
    "body" => $_REQUEST['body'],                   //メール本文
    "from_address" => $_REQUEST['from_address'],   //Fromアドレス
    "from_txt" => $_REQUEST['from_txt'],           //Fromテキスト
    "returnpath" => $_REQUEST['returnpath'],      //メール返信先(エラー時)
    "auto_return" => $_REQUEST['auto_return'],     //自動リターン集計
    "replyto" => $_REQUEST['replyto'],             //メール返信先
    "start_sending" => $_REQUEST['start_sending'], //メール配信開始日時について
    "year" => $_REQUEST['year'],                   //メール配信日(年)
    "month" => $_REQUEST['month'],                     //メール配信日(月)
    "day" => $_REQUEST['day'],                     //メール配信日(日)
    "hour" => $_REQUEST['hour'],                   //メール配信日(時)
    "min" => $_REQUEST['min']                      //メール配信日(分)
);
   
//送信するファイル名のリスト
$post_data_files = array('file', 'file_to_attach');
   
//APIのHostを設定
$api_host = "example.com";
   
//APIのPathを設定
$api_path = "/API/set";

//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){
    if((is_numeric($val) || is_string($val)) && $val !== ""){
        $body .= "--" . $boundary . "\r\n";
        $body .= "Content-Disposition: form-data; name=\"" . $key . "\"\r\n";
        $body .= "\r\n" . $val . "\r\n";
        $body .= "--" . $boundary . "\r\n";
    }
}

//ファイルデータをAPIに送信できるよう変換
foreach ($post_data_files as $val){
    if($_FILES[$val]['name']){
        $body .= "--" . $boundary . "\r\n";
        $body .= "Content-Disposition: form-data; name=\"" . $val . "\"; filename=\"";
        $body .= $_FILES[$val]['name'] . "\"\r\n";
        $body .= "Content-Type: " . $_FILES[$val]['type'] . "\r\n\r\n";
        $body .= "" . join("", file($_FILES[$val]['tmp_name'])) . "\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);

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

exit;

?>

サンプルスクリプト解説

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

//APIへ送信するデータ
//$_REQUESTの部分については、可能であれば$_POSTか$_GETを指定してください
//今回はサンプルの為、汎用性を考えて$_REQUESTとします
$post_data = array(
    "login_id" => "login@example.com",             //ログインID
    "password" => "password",                      //ログインパスワード
    "subject" => $_REQUEST['subject'],             //メールタイトル
    "body" => $_REQUEST['body'],                   //メール本文
    "from_address" => $_REQUEST['from_address'],   //Fromアドレス
    "from_txt" => $_REQUEST['from_txt'],           //Fromテキスト
    "returnpath" => $_REQUEST['returnpath'],       //メール返信先(エラー時)
    "auto_return" => $_REQUEST['auto_return'],     //自動リターン集計
    "replyto" => $_REQUEST['replyto'],             //メール返信先
    "start_sending" => $_REQUEST['start_sending'], //メール配信開始日時について
    "year" => $_REQUEST['year'],                   //メール配信日(年)
    "month" => $_REQUEST['month'],                     //メール配信日(月)
    "day" => $_REQUEST['day'],                     //メール配信日(日)
    "hour" => $_REQUEST['hour'],                   //メール配信日(時)
    "min" => $_REQUEST['min']                      //メール配信日(分)
);
   
//送信するファイル名のリスト
$post_data_files = array('file', 'file_to_attach');
   
//APIのHostを設定
$api_host = "example.com";
   
//APIのPathを設定
$api_path = "/API/set";

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){
    if((is_numeric($val) || is_string($val)) && $val !== ""){
        $body .= "--" . $boundary . "\r\n";
        $body .= "Content-Disposition: form-data; name=\"" . $key . "\"\r\n";
        $body .= "\r\n" . $val . "\r\n";
        $body .= "--" . $boundary . "\r\n";
    }
}

//ファイルデータをAPIに送信できるよう変換
foreach ($post_data_files as $val){
    if($_FILES[$val]['name']){
        $body .= "--" . $boundary . "\r\n";
        $body .= "Content-Disposition: form-data; name=\"" . $val . "\"; filename=\"";
        $body .= $_FILES[$val]['name'] . "\"\r\n";
        $body .= "Content-Type: " . $_FILES[$val]['type'] . "\r\n\r\n";
        $body .= "" . join("", file($_FILES[$val]['tmp_name'])) . "\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);

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

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

//結果を取得し表示
print "status:"  . $result_xml->status  . "<br>"; //ステータス
print "code:"    . $result_xml->code    . "<br>"; //コード
print "message:" . $result_xml->message . "<br>"; //メッセージ
print "valid:"   . $result_xml->valid   . "<br>"; //有効件数
print "error:"   . $result_xml->error   . "<br>"; //無効件数
print "task_id:" . $result_xml->task_id . "<br>"; //配信タスクID

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

status:OK
code:200
message:本登録に成功しました
valid:123
error:45
task_id:67

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

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

サンプルスクリプト解説

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

//APIへ送信するデータ
//$_REQUESTの部分については、可能であれば$_POSTか$_GETを指定してください
//今回はサンプルの為、汎用性を考えて$_REQUESTとします
$post_data = array(
    "login_id" => "login@example.com",             //ログインID
    "password" => "password",                      //ログインパスワード
    "subject" => $_REQUEST['subject'],             //メールタイトル
    "body" => $_REQUEST['body'],                   //メール本文
    "from_address" => $_REQUEST['from_address'],   //Fromアドレス
    "from_txt" => $_REQUEST['from_txt'],           //Fromテキスト
    "returnpath" => $_REQUEST['returnpath'],       //メール返信先(エラー時)
    "auto_return" => $_REQUEST['auto_return'],     //自動リターン集計
    "replyto" => $_REQUEST['replyto'],             //メール返信先
    "start_sending" => $_REQUEST['start_sending'], //メール配信開始日時について
    "year" => $_REQUEST['year'],                   //メール配信日(年)
    "month" => $_REQUEST['month'],                     //メール配信日(月)
    "day" => $_REQUEST['day'],                     //メール配信日(日)
    "hour" => $_REQUEST['hour'],                   //メール配信日(時)
    "min" => $_REQUEST['min']                      //メール配信日(分)
);
   
//送信するファイル名のリスト
$post_data_files = array('file', 'file_to_attach');
   
//APIのHostを設定
$api_host = "example.com";
   
//APIのPathを設定
$api_path = "/API/set";

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){
    if((is_numeric($val) || is_string($val)) && $val !== ""){
        $body .= "--" . $boundary . "\r\n";
        $body .= "Content-Disposition: form-data; name=\"" . $key . "\"\r\n";
        $body .= "\r\n" . $val . "\r\n";
        $body .= "--" . $boundary . "\r\n";
    }
}

//ファイルデータをAPIに送信できるよう変換
foreach ($post_data_files as $val){
    if($_FILES[$val]['name']){
        $body .= "--" . $boundary . "\r\n";
        $body .= "Content-Disposition: form-data; name=\"" . $val . "\"; filename=\"";
        $body .= $_FILES[$val]['name'] . "\"\r\n";
        $body .= "Content-Type: " . $_FILES[$val]['type'] . "\r\n\r\n";
        $body .= "" . join("", file($_FILES[$val]['tmp_name'])) . "\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);

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

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

//結果を取得し表示
print "status:"  . $result_xml->status  . "<br>"; //ステータス
print "code:"    . $result_xml->code    . "<br>"; //コード
print "message:" . $result_xml->message . "<br>"; //メッセージ
print "valid:"   . $result_xml->valid   . "<br>"; //有効件数
print "error:"   . $result_xml->error   . "<br>"; //無効件数
print "task_id:" . $result_xml->task_id . "<br>"; //配信タスクID

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

status:OK
code:200
message:本登録に成功しました
valid:123
error:45
task_id:67

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

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

UTF-8での配信

スリーメールでは、通常、ユーザーに届くメールの文字コードはJISまたはSJISとなっています。これは日本国内のユーザーのみにメールを送信するためには適切な文字コードですが、国外を含む世界中に送信するメールについては文字コードをUTF-8とするのが一般的です。「use_utf8」を「1」とすることにより、配信時の文字コードとしてUTF-8が使われるようになります。

「use_utf8」を「1」とする場合、配信リスト(file)や件名(subject)、本文(body)、HTMLメール(file_to_attach)など、すべての項目をUTF-8でエンコードしてください。

「use_utf8」で「1」を指定した場合、「高度な設定」の「UTF-8を使う」画面で「UTF-8を使わない」と設定していた場合でも、UTF-8が使われます。

ブロック差し込み機能

メールの本文のうち、特定の文面（範囲）は特定のユーザーにのみ表示されるようにしたい、という場合に、ブロック差し込み機能がお使いいただけます。

たとえば、次のようなメールを送りたいものとします。

今日の星占い

おひつじ座のあなた：
○○○○○でしょう。

おうし座のあなた：
○○○○○でしょう。

ふたご座のあなた：
○○○○○でしょう。

このうち、それぞれのユーザーには必要な部分だけが本文に含まれるようにしたいとします。
たとえば、おうし座のユーザーに届くメールは次のようにしたいとします。

今日の星占い

おうし座のあなた：
○○○○○でしょう。

この場合、本文を次のようにしてください。

今日の星占い

[% IF "$val1" -%]
おひつじ座のあなた：
○○○○○でしょう。
[% END -%]

[% IF "$val2" -%]
おうし座のあなた：
○○○○○でしょう。
[% END -%]

[% IF "$val3" -%]
ふたご座のあなた：
○○○○○でしょう。
[% END -%]

ただし、$val1にあたるカラムは、おひつじ座のユーザーだけが「1」となっていて、$val2はおうし座のユーザーのみ「1」、$val3以降も同様となっているものとします。この機能を使う際は、/API/set のリクエストパラメーターとして「block_replace」に「1」を設定する必要がありますので、ご注意ください。

配信キャリアにつきまして

/API/setで配信設定を行った場合、配信履歴に含まれる「配信キャリア」の項目は空となります。