Devenia IMAP Intake

IMAP の受信トレイを WordPress プラグインにつなぐ

既存の IMAP メールボックスから、PHP インターフェースを通じてメッセージと添付ファイルを読み取れます。読み取るタイミングと結果の使い方は、呼び出し側のプラグインが決めます。

バージョン 1.0.1 · GPL-2.0-or-later

封筒と添付書類を扱うメール受信装置のアール・デコ風イラスト。

一つのメールボックスから、明確に引き渡す

プラグインがサーバー、ポート、フォルダー、認証情報を渡します。Devenia IMAP Intake は検証済みの TLS 接続でフォルダーを読み取り専用で開き、メッセージヘッダー、送信者アドレス、デコード済み添付ファイルのバイト列を返します。元のメッセージはフォルダーに残り、既読状態も保たれます。

接続のタイミング、アクセス制御、再試行、重複排除、保存はプラグイン側の責任です。また、取得するメッセージ全体のサイズ上限も取得ごとに設定します。

メッセージを読み、後はプラグインへ。

メッセージはメールボックスに残ります。受信側はメッセージを読み取り添付ファイルをデコードし、呼び出し側のプラグインが独自のルールでその後の処理を決めます。

IMAP メールボックスから Devenia IMAP Intake を通じて WordPress プラグインにメッセージを渡す図。

受信側はメールボックスとコードをつなぎます。メッセージの処理方法は決めません。

例:共有受信トレイを処理する

[email protected] 宛てのメッセージを処理する WordPress プラグインを考えてみましょう。開発者は既存の IMAP メールボックスに接続し、メッセージのサイズ上限を設定します。受信側はメッセージと添付ファイルを返し、呼び出し側のプラグインが処理済みか確認して、それぞれの保存や処理方法を決めます。

この例は説明用です。受信側は開発者向けの読み取りインターフェースであり、ウェブメールでも SMTP による送信機能でもありません。

メッセージ ID は有効な範囲で使う

UID は、特定のアカウント、フォルダー、UIDVALIDITY の組み合わせの中でのみメッセージを識別します。カーソルを再利用する前に、現在の UIDVALIDITY を保存済みの値と比較してください。

UIDVALIDITY

選択したフォルダーの現在の UID 系列を識別します。

UID

そのアカウント、フォルダー、UID 系列内のメッセージを識別します。

必要環境とダウンロード

WordPress 6.9 以降、OpenSSL と mbstring を備えた PHP 8.1 以降、信頼できる CA 証明書、有効な TLS 証明書を持つ IMAP サーバーが必要です。接続は暗黙的 TLS または STARTTLS に対応します。

上の ZIP をダウンロードし、本番のメールボックスで使う前にテスト環境のコピーで連携を確認してください。

WordPress の プラグイン → 新規プラグインを追加 → プラグインのアップロード を開き、ZIP を選択して Devenia IMAP Intake をインストール、有効化します。有効なプラグインの読み込み後に、自分のプラグインからインターフェースを呼び出してください。メールボックスの認証情報は、アプリケーションの保護された設定に保存します。

フォルダーを開いてメッセージを読む

この例では予約済みドメインを使います。$password は保護された設定から、$saved_uid_validity は自分のアプリケーションから渡してください。初回はカーソルを保存する前に、フォルダーの UIDVALIDITY を確認します。fetch() はデコード前のメッセージ全体にバイト上限を適用します。

use Devenia\ImapIntake\Mailbox;

$mailbox = Mailbox::open( array(
    'host'       => 'imap.example.com',
    'port'       => 993,
    'username'   => '[email protected]',
    'password'   => $password,
    'folder'     => 'INBOX',
    'encryption' => 'ssl',
    'timeout'    => 15,
) );

if ( is_wp_error( $mailbox ) ) {
    return $mailbox;
}

try {
    $validity = $mailbox->uid_validity();
    $uids = $mailbox->uids();
    if ( is_wp_error( $uids ) ) {
        return $uids;
    }

    if ( $validity !== $saved_uid_validity ) {
        return new WP_Error( 'mailbox_changed', '続行する前に保存済みのカーソルを確認してください。' );
    }

    if ( $uids ) {
        $message = $mailbox->fetch( $uids[0], wp_max_upload_size() );
        if ( is_wp_error( $message ) ) {
            return $message;
        }
    }
} finally {
    $mailbox->close();
}

インターフェースは Mailbox::open()、uid_validity()、uids()、fetch()、close() を提供します。取得したメッセージにはヘッダー、送信者アドレス、デコード済みバイト列を含む添付ファイルが含まれます。

本番処理では、エラーを処理し、独自のカーソルで UID を選び、方針に従って送信者を検証してください。後続処理が成功してから完了を記録します。IMAP 読み取りに失敗した後は新しいセッションを開いてください。

接続できない場合は、サーバー名、ポート、TLS モード、認証情報、信頼できる証明書チェーンを確認してください。メッセージがバイト上限を超える場合は、再試行前にアプリケーションでの扱いを決めてください。

自分の WordPress プラグインでメッセージを読む

プラグインをダウンロードし、必要環境を確認して、アプリケーションからの接続をテストしてください。

封筒と添付書類を扱うメール受信装置のアール・デコ風イラスト。