Devenia IMAP Intake
将 IMAP 邮箱接入你的 WordPress 插件
通过 PHP 接口读取现有 IMAP 邮箱中的邮件和附件。何时读取、如何处理结果,由你的插件决定。
版本 1.0.1 · GPL-2.0-or-later
一个邮箱,清晰交接
你的插件提供服务器、端口、文件夹和登录凭据。Devenia IMAP Intake 通过经验证的 TLS 连接以只读方式打开文件夹,返回邮件头、发件人地址和附件解码后的字节。原邮件仍保留在文件夹中,已读状态也不会改变。
何时连接,以及访问控制、重试、去重和存储,均由你的插件负责。插件还须为每次读取设置完整邮件的大小上限。
读取邮件,后续交给你的插件。
邮件保留在邮箱中。接收器读取邮件并解码附件;你的插件按自己的规则决定下一步如何处理。
接收器将邮箱连接到你的代码,但不会替你决定邮件的处理方式。
示例:处理共享收件箱
假设一个 WordPress 插件需要处理发往 [email protected] 的邮件。开发者将它接入现有 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 模式、凭据及受信任的证书链。如果邮件超过字节上限,请先决定应用如何处理,再重试。
