<?php
/**
* SeekQuarry/Yioop --
* Open Source Pure PHP Search Engine, Crawler, and Indexer
*
* Copyright (C) 2009 - 2026 Chris Pollett chris@pollett.org
*
* LICENSE:
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*
* END LICENSE
*
* @author Chris Pollett chris@pollett.org (initial MediaJob class
* and subclasses based on work of Pooja Mishra for her master's)
* @license https://www.gnu.org/licenses/ GPL3
* @link https://www.seekquarry.com/
* @copyright 2009 - 2026
* @filesource
*/
namespace seekquarry\yioop\library\media_jobs;
use seekquarry\yioop\configs as C;
use seekquarry\yioop\library as L;
use seekquarry\yioop\library\mail\MailScheduledDispatcher;
use seekquarry\yioop\models\MailAccountModel;
use seekquarry\yioop\models\MailScheduledModel;
use seekquarry\yioop\library\mail\DkimKey;
use seekquarry\yioop\library\mail\MailSiteFactory;
use seekquarry\yioop\library\mail\UnsubscribeToken;
use seekquarry\yioop\models\GroupModel;
use seekquarry\yioop\models\MailSuppressionModel;
/**
* MediaJob class for sending out emails from a Yioop instance (either in
* response to account registrations or in response to group posts and similar
* activities)
*/
class BulkEmailJob extends MediaJob
{
/**
* SmtpClient used to send mail from the media updater
* @var object
*/
public $smtp_client;
/**
* Site-wide suppression list, consulted before sending list mail so
* that an address that has unsubscribed from everything is skipped
* @var object
*/
public $suppression_model;
/**
* Handle to the local mail store, used to read and clear the bot
* mailbox that receives unsubscribe mail
* @var object
*/
public $mail_storage;
/**
* Group model, used to turn off one group's mail for a member when a
* member-and-group unsubscribe arrives
* @var object
*/
public $group_model;
/**
* Set up the SmtpClient object used to actually send mail, plus the
* models and mail store the unsubscribe reader needs.
*/
public function init()
{
$this->smtp_client = MailSiteFactory::outboundSmtpClient();
$this->suppression_model = new MailSuppressionModel();
$this->group_model = new GroupModel();
$this->mail_storage = MailSiteFactory::storage();
}
/**
* Reads the root account's INBOX and acts on each unsubscribe
* message that has arrived for the bot. A recipient who clicks the
* mailto form of a List-Unsubscribe header sends mail to the bot
* address (the configured sender) with the subject "unsubscribe
* <token>"; because the bot address is a root alias, that mail is
* delivered into the root INBOX. That INBOX may also hold a great
* deal of unrelated personal mail, so rather than open every message
* this asks the folder's search index for just the ones whose
* Subject, From, or To mention the marker word. Each candidate is
* then confirmed to begin "unsubscribe " and to have been delivered
* to the bot address before it is acted on, and only those are
* removed, leaving the root account's other mail alone. When the site
* runs no local mail there is no such mailbox and this does nothing.
*/
public function processBotMailbox()
{
$mailbox = strtolower((string)C\ROOT_USERNAME);
if (!$this->mail_storage->folderExists($mailbox, "INBOX")) {
return;
}
$marker = "unsubscribe ";
$bot_address = strtolower(MailSiteFactory::botAddress());
$removed = false;
/*
The search index narrows the mailbox to the few messages
whose Subject, From, or To mention the marker word, read from
a single index file rather than by opening every message. On
a personal root INBOX of tens of thousands of messages this
returns a handful of candidates instead of the whole mailbox,
which is what stalled the media updater.
*/
$candidates = $this->mail_storage->searchMessages($mailbox,
"INBOX", trim($marker));
foreach ($candidates as $uid) {
$headers = DkimKey::parseHeaders((string)$this->mail_storage
->messageHeaderBytes($mailbox, "INBOX", $uid));
$subject = empty($headers['subject'][0]) ? "" :
trim(str_replace(["\r\n", "\n"], "",
$headers['subject'][0]));
$delivered_to = empty($headers['delivered-to'][0]) ? "" :
strtolower(trim($headers['delivered-to'][0]));
if (stripos($subject, $marker) === 0 &&
$delivered_to === $bot_address) {
$this->applyUnsubscribeToken(trim(substr($subject,
strlen($marker))));
$this->mail_storage->setFlags($mailbox, "INBOX", $uid,
["\\Deleted"]);
$removed = true;
}
}
if ($removed) {
$this->mail_storage->expunge($mailbox, "INBOX");
}
}
/**
* Acts on one unsubscribe token after checking its signature. A
* member-and-group token turns off that group's mail for that
* member; a whole-site token adds the address to the suppression
* list. A token whose signature does not verify (a forged or stray
* request) is logged and ignored, so no one can unsubscribe an
* address or group they were not handed a token for.
*
* @param string $token the signed token taken from the message
* @return bool true when a valid token was acted on, false otherwise
*/
public function applyUnsubscribeToken($token)
{
$group = UnsubscribeToken::parse($token);
if ($group !== false) {
$this->group_model->setMailSubscription($group['user_id'],
$group['group_id'], 0);
return true;
}
$email = UnsubscribeToken::parseEmail($token);
if ($email !== false) {
$this->suppression_model->suppress($email);
return true;
}
L\crawlLog("Ignoring unsubscribe token that did not verify");
return false;
}
/**
* Reports whether a queued message should be held back because its
* recipient has unsubscribed from all of this site's mail. Only list
* mail is held back: a message counts as list mail when it carries a
* List-Unsubscribe header offering the recipient a way to opt out.
* Transactional mail such as a password reset carries no such header
* and is always sent, so a suppressed address can still recover their
* account.
*
* @param array $email queued message as the array
* [subject, from, to, body, headers]
* @return bool true when the recipient is suppressed and the message
* is list mail, so it should not be sent
*/
public function suppressedRecipient($email)
{
if (empty($email[4]['List-Unsubscribe'])) {
return false;
}
if (!$this->suppression_model->isSuppressed($email[2])) {
return false;
}
L\crawlLog("Skipping suppressed recipient {$email[2]} " .
"about {$email[0]}");
return true;
}
/**
* Bulk mail and scheduled-mail dispatch are both periodic
* tasks owned by this job. checkPrerequisites unconditionally
* returns true so the scheduled-mail path is reached every
* media_updater cycle; the bulk-mail path inside
* nondistributedTasks is self-gating (it returns early if no
* mail file is aged past MAIL_AGGREGATION_TIME), so always
* running it costs essentially nothing when bulk mail isn't
* configured.
*
* @return true always
*/
public function checkPrerequisites()
{
return true;
}
/**
* Function to send emails to mailer batches created by
* smtp_client. This function would periodically be invoked and
* send emails reading data from the text files.
*/
public function nondistributedTasks()
{
$this->processBotMailbox();
$scheduled_model = new MailScheduledModel();
$account_model = new MailAccountModel();
$stats = MailScheduledDispatcher::dispatch(
$scheduled_model, $account_model);
if (($stats['claimed'] ?? 0) > 0) {
L\crawlLog("Scheduled mail: claimed " .
$stats['claimed'] . ", sent " .
$stats['sent'] . ", failed " .
$stats['failed'] . ", skipped " .
$stats['skipped']);
}
$mail_directory = C\WORK_DIRECTORY . self::MAIL_FOLDER;
if (!file_exists($mail_directory)) {
return;
}
$files = glob($mail_directory."/*.txt");
if (!isset($files[0])) {
return;
}
$sendable_file = false;
foreach ($files as $email_file) {
if (time() - filemtime($email_file) >
C\MAIL_AGGREGATION_TIME) {
$sendable_file = $email_file;
break;
}
}
if (!$sendable_file) {
return;
}
L\crawlLog("Using Mail Directory:" . $mail_directory);
$emails_string = file_get_contents($sendable_file);
unlink($sendable_file);
$emails = explode(self::MESSAGE_SEPARATOR, $emails_string);
foreach ($emails as $serialized_email) {
$email = unserialize($serialized_email);
if (is_array($email) && count($email) >= 4 &&
!$this->suppressedRecipient($email)) {
L\crawlLog(
"Sending email to {$email[2]} about {$email[0]}");
$this->smtp_client->sendImmediate(
$email[0], $email[1], $email[2], $email[3], [],
$email[4] ?? []);
}
}
}
/**
* Emails a list of emails provided by the name server to the media updater
* client
*
* @param array $tasks contains emails which should be sent out
* @return mixed data to send back to name server (in this case the name
* of the email file that was completely sent)
*/
public function doTasks($tasks)
{
if (!isset($tasks["name"]) || !isset($tasks["data"])) {
L\crawlLog("...Email Task received incomplete !");
return false;
}
L\crawlLog("----Email file name: {$tasks['name']}");
$emails = explode(self::MESSAGE_SEPARATOR, $tasks["data"]);
foreach ($emails as $serialized_email) {
$email = unserialize($serialized_email);
if (is_array($email) && count($email) >= 4 &&
!$this->suppressedRecipient($email)) {
L\crawlLog("Sending email to {$email[2]} about {$email[0]}");
$this->smtp_client->sendImmediate(
$email[0], $email[1], $email[2], $email[3], [],
$email[4] ?? []);
}
}
return false;
}
/**
* Hands the name server one aggregated mail file to dispatch to a
* worker for sending. It picks the first mail file that has sat
* long enough to be ready (older than MAIL_AGGREGATION_TIME),
* returns that file's name and contents as the task, and removes
* the file so the same batch is not handed out and sent again on
* a later cycle.
*
* @param int $machine_id id of client requesting data (not used)
* @param array $data not used
* @return mixed array with the mail file's name and its contents
* for a worker to send; false when no mail directory exists
* or no file has aged past MAIL_AGGREGATION_TIME
*/
public function getTasks($machine_id, $data = null)
{
$mail_directory = C\WORK_DIRECTORY . self::MAIL_FOLDER;
if (!file_exists($mail_directory)) {
return false;
}
$files = glob($mail_directory . "/*.txt");
$sendable_file = false;
foreach ($files as $email_file) {
if (time() - filemtime($email_file) >
C\MAIL_AGGREGATION_TIME) {
$sendable_file = $email_file;
break;
}
}
if (!$sendable_file) {
return false;
}
$file_name = str_replace($mail_directory . "/","", $sendable_file);
$task = [];
$task["name"] = $file_name;
$task["data"] = file_get_contents($sendable_file);
unlink($sendable_file);
return $task;
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software