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);
エラーメールを検索する
エラーメールを検索する際には bounces メソッドを使います。
$search_criteria = [ 'server_composition' => 'pro' ]; $emails = $client->bounces($search_criteria);
この server_composition は必須です。その他のパラメーターは後述します。
検索に利用できるパラメーター
検索条件はDeliveries - Manual - Customers Mail Cloudにありますが、以下のパラメータが利用できます。
| パラメータ | 必須 | データ型 | 説明 |
|---|---|---|---|
| api_user | Yes | ASCII | ユーザ認証に使用するIDを指定します。 |
| api_key | Yes | ASCII | ユーザ認証に使用するシークレットキーを指定します。 |
| server_composition | Yes | UTF-8 | 操作の対象となるサーバ構成の名称を指定します。 |
| from | No | ASCII | 指定された文字列にFromアドレスが部分一致するデータを検索します。 |
| to | No | ASCII | 指定された文字列にToアドレスが部分一致するデータを検索します。 |
| api_data | No | ASCII | 指定された文字列にX-Api-Dataのヘッダ値が部分一致するデータを検索します。 |
| status | No | INTEGER | 指定されたエラーステータスに該当するデータを検索します。 |
| start_date | No | DATE | バウンスメールの受信日を基準とした期間検索を行うために検索開始日(yyyy-mm-dd形式)を指定します。 制約：start_dateはend_dateと等しいか過去日を指定しなければなりません。 デフォルト：APIを実行した日 |
| end_date | No | DATE | バウンスメールの受信日を基準とした期間検索を行うために検索終了日(yyyy-mm-dd形式)を指定します。 デフォルト：APIを実行した日 |
| date | No | DATE | バウンスメールの受信日(yyyy-mm-dd形式)を指定します。 制約：hour,minute パラメータを指定する場合、本パラメータは必須となります。本パラメータが指定された場合、start_date, end_date への指定値は無視されます。 |
| 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" }
レスポンス
結果は、 Bounce クラスのインスタンスの配列で返ってきます。
$bounce = $emails[0]; echo " Status: " . $bounce->status . "\n"; echo " Reason: " . $bounce->reason . "\n"; echo " From: " . $bounce->from . "\n"; echo " To: " . $bounce->to . "\n"; echo " Created: " . $bounce->created . "\n";
エラーの場合
たとえば未来の日付にすると、検索エラーになります。
try {
$emails = $client->bounces([
'server_composition' => 'sandbox',
'start_date' => date('Y-m-d', strtotime('+1 day'))
]);
} catch (CustomersMailCloudError $e) {
echo "Error Message: " . $e->getMessage() . "\n";
echo "Error Codes: " . implode(', ', $e->getAllErrorCodes()) . "\n";
}
エラーの原因について
エラーメールになった原因は status プロパティの数字（コード）で判断できます。一覧でまとめると以下の通りです。
| ステータス | エラー理由 | 発生原因 |
|---|---|---|
| 1 | ホスト不明 | DNSによるドメイン解決ができなかった。 |
| 2 | ユーザ不明 | メールアドレスが存在しない。 |
| 3 | 再送タイムアウト | 宛先サーバーへ接続できない、一時エラー応答が返されたため、再送を行ったが時間内に再送が完了しなかった。 |
| 4 | 受信拒否 | 宛先サーバーのポリシーによりメール受信を拒否された。 |
| 5 | 容量オーバー | メールボックスの容量や、メールサーバーのディスク領域の制限を超えたため、宛先サーバーがメールを受信できなかった。 |
| 6 | 転送エラー | 送信した宛先アドレスと異なるアドレスへのメール送信が失敗した。受信者側の設定で宛先アドレスにメールを保存した後、別アドレスに転送している場合、宛先アドレスにはメールが届いている可能性がある。 |
| 7 | 受信サーバエラー | 宛先サーバーの設定ミスによりメール送信が失敗した(25番ポートにSMTP認証を設定している、DNSによるドメイン解決を行って接続したにもかかわらず宛先サーバーが管理するドメインではないなど)。 |
| 8 | サイズオーバー | メールサイズが大きすぎるため、宛先サーバーが受信を拒否した。 |
| 9 | アドレス形式エラー | 宛先メールアドレスが、メールアドレスの形式に従っていない。 |
| 10 | 配信停止アドレス | 過去にユーザ不明等の理由により送信エラーとなったメールアドレスであるため、再度のメール送信を抑止した。 |
| 11 | 購読解除 | 購読解除リストに登録済みのメールアドレスのため、再度のメール送信を抑止した。 |
| 99 | その他エラー | 宛先サーバーが恒久エラーを応答したため、メール送信に失敗した。 |
コードについて
コードは goofmint/CustomersMailCloud-php: PHP SDK for Customers Mail Cloudで公開しています。不具合などがあれば、ご指摘ください。なお、現状のSDKは非公式になるので、公式サポートへの問い合わせはご遠慮ください。
まとめ
PHPからメール送信を行う際に、ライブラリを使うことでとても簡単に実装ができます。ぜひお試しください。
