Customers Mail Cloud用のPHPライブラリで送信済メールのステータスを検索、取得する

PHPでメール送信を行う際にはPHPMailerやmb_send_mailを使うのが基本だと思いますが、環境によってはSMTPが使えない場合もあります。そうした時にはWeb API経由でのメール送信が便利です。

Customers Mail Cloudにはメール送信用のAPIが用意されていますが、さらに手軽に使いやすくするライブラリを開発しています。今回は、送信済メールのステータスを検索、取得する方法を紹介します。

customers-mail-cloud/php-sdk - Packagist

インストール

インストールは composer コマンドで行います。

composer require customers-mail-cloud/php-sdk

使い方

まずライブラリをインポートします。

require_once 'vendor/autoload.php';

use CustomersMailCloud\CustomersMailCloud;

次に初期化します。 Node.jsでメールを送信する - Email Sending API - Customers Mail Cloud ブログブログを参考にAPIユーザ、APIキーを作成してください。

$api_user = 'API_USER';
$api_key  = 'API_KEY';
// Initialize client
$client = new CustomersMailCloud($api_user, $api_key);

メールを検索する

メールを検索する際には deliveries メソッドを使います。

$search_criteria = [
  'server_composition' => 'pro',
  'date' => date('Y-m-d', strtotime('-1 day')) // 1日前の日付
];
$emails = $client->deliveries($search_criteria);

この server_composition と date は必須です。その他のパラメーターは後述します。

検索に利用できるパラメーター

検索条件はDeliveries - Manual - Customers Mail Cloudにありますが、以下のパラメータが利用できます。

パラメータ	必須	データ型	説明
server_composition	Yes	UTF-8	操作の対象となるサーバ構成の名称を指定します。
from	No	ASCII	指定された文字列にFromアドレスが部分一致するデータを検索します。
to	No	ASCII	指定された文字列にToアドレスが部分一致するデータを検索します。
api_data	No	ASCII	指定された文字列にX-Api-Dataのヘッダ値が部分一致するデータを検索します。
status	No	ASCII	指定された配信ステータスに該当するメールアドレスを検索します。
date	Yes	DATE	検索対象日(yyyy-mm-dd形式)を指定します。制約：未来日付は指定できません。
hour	No	INTEGER	dateで指定された日の1時間分の配信ステータスとメールアドレスを検索します。範囲：0-23 制約：未来時刻は指定できません。
minute	No	INTEGER	date, hour で指定された日時の1分間分の配信ステータスとメールアドレスを検索します。範囲：0-59 制約：現在時刻から2分以前の値を指定してください。
p	No	INTEGER	参照するページ位置を指定します。デフォルト：0
r	No	INTEGER	1ページに表示するレコード数を指定します。デフォルト：10 最大取得件数：100
search_option	No	ASCII	完全一致検索を行う場合、このオプションを指定します。詳細は後述を参照ください。

search_optionについて

fromとto、api_data は検索オプションをどのパラメータに適用するかを指定します。検索方法を変更したいパラメータのみを指定してください。search_option の指定が無い場合は、部分一致で検索します。

{
  "from" : "full",
  "to" : "full",
  "api_data" : "full"
}

レスポンス

結果は、 Delivery クラスのインスタンスの配列で返ってきます。

$delivery = $emails[0];
echo "  Subject: " . $delivery->subject . "\n";
echo "  Status: " . $delivery->status . "\n";
echo "  From: " . $delivery->from . "\n";
echo "  To: " . $delivery->to . "\n";

エラーの場合

たとえば未来の日付にすると、検索エラーになります。

try {
  $deliveries = $client->deliveries([
      'server_composition' => 'sandbox',
      'date' => date('Y-m-d', strtotime('+1 day'))
  ]);
} catch (CustomersMailCloudError $e) {
  echo "Error Message: " . $e->getMessage() . "\n";
  echo "Error Codes: " . implode(', ', $e->getAllErrorCodes()) . "\n";
}

コードについて

コードは goofmint/CustomersMailCloud-php: PHP SDK for Customers Mail Cloudで公開しています。不具合などがあれば、ご指摘ください。なお、現状のSDKは非公式になるので、公式サポートへの問い合わせはご遠慮ください。

まとめ

PHPからメール送信を行う際に、ライブラリを使うことでとても簡単に実装ができます。ぜひお試しください。