MailService
in package
Outbound mail: Amazon SES when configured, otherwise PHP mail().
Honors mail_suppress and user/profile subscribe=-1.
Prefer sendTransactional() / sendBulk() so SES can treat streams differently.
Table of Contents
Constants
- BULK_MAX_PER_SECOND : mixed = 5
- Soft local pace for bulk sends (unlikely to hit on normal SES latency).
- TYPE_BULK : mixed = 'bulk'
- TYPE_TRANSACTIONAL : mixed = 'transactional'
Properties
- $bulkPacePerSecond : int
- $bulkSendTimestamps : array<int, float>
Methods
- appendBulkUnsubscribeFooter() : string
- Append a visible unsubscribe footer for bulk mail with a signed URL.
- buildOutboundHeaders() : array<int, array{Name: string, Value: string}>
- Headers for outbound mail. List-Unsubscribe* only on signed bulk mail.
- computeCheck() : mixed
- getBulkPacePerSecond() : int
- getSuppressReason() : string|null
- Current suppress reason for an address, or null if not suppressed.
- isOneClickUnsubscribeRequest() : bool
- RFC 8058 one-click body detection (no session required).
- isRateLimited() : bool
- Whether a sendDetailed* result indicates SES rate limiting / throttling.
- isRateLimitThrowable() : bool
- Detect SES throttle / rate-limit from exception type or message text.
- isSesConfigured() : bool
- Whether SES is configured for outbound mail.
- isSuppressed() : bool
- isUserOptedOut() : bool
- True when user or linked profile has subscribe = -1 (no mail).
- normalizeEmail() : string
- optOutSubscribeByEmail() : void
- Set subscribe=-1 on profile and lti_user rows matching this email.
- paceBulkSend() : void
- Soft pace for bulk sends toward getBulkPacePerSecond() average.
- recordSesEvent() : bool
- Append a row to mail_ses_events (audit of SES notification + action taken).
- replyToAddress() : string|null
- Optional Reply-To for all transports (where human replies should go).
- send() : mixed
- sendBulk() : mixed
- Campaign / list-style mail to many recipients.
- sendDetailed() : array<string|int, mixed>
- sendDetailedBulk() : array<string|int, mixed>
- sendDetailedTransactional() : array<string|int, mixed>
- sendTransactional() : mixed
- One-to-one / system response mail (key approval, notices, etc.).
- sesEventsTableExists() : bool
- Whether the mail_ses_events table exists.
- setBulkPacePerSecond() : void
- Set local bulk pacing target (messages/sec). 0 disables pacing.
- shouldSkipSend() : bool
- Pre-send gate: skip before calling SES/mail().
- suppress() : void
- Upsert an address into the suppress list.
- suppressReasonBlocksType() : bool
- Whether this suppress reason blocks the given mail type.
- suppressTableExists() : bool
- Whether the mail_suppress table exists.
- transport() : "ses"|"php"
- Active transport name when mail is enabled.
- configurationSetForType() : string|null
- Configuration set for this mail type (bulk can use a separate set).
- fromAddress() : string
- From for all transports (SES and PHP mail()).
- sendDetailedWithType() : array{success: bool, transport: string, error: ?string, message_id: ?string, disabled: bool, suppressed: bool, rate_limited: bool, type: string}
- sendResult() : bool|null
- sendViaPhpMail() : array<string|int, mixed>
- sendViaSes() : array<string|int, mixed>
- unsubscribeUrl() : string
Constants
BULK_MAX_PER_SECOND
Soft local pace for bulk sends (unlikely to hit on normal SES latency).
public
mixed
BULK_MAX_PER_SECOND
= 5
TYPE_BULK
public
mixed
TYPE_BULK
= 'bulk'
TYPE_TRANSACTIONAL
public
mixed
TYPE_TRANSACTIONAL
= 'transactional'
Properties
$bulkPacePerSecond
private
static int
$bulkPacePerSecond
= 0
Target bulk sends per second (0 = no pacing). Default off; CLI batch sets this.
$bulkSendTimestamps
private
static array<int, float>
$bulkSendTimestamps
= array()
Timestamps of recent bulk send attempts (this request).
Methods
appendBulkUnsubscribeFooter()
Append a visible unsubscribe footer for bulk mail with a signed URL.
public
static appendBulkUnsubscribeFooter(string $message, string $type[, mixed $unsubscribe_url = null ]) : string
Parameters
- $message : string
- $type : string
- $unsubscribe_url : mixed = null
Return values
stringbuildOutboundHeaders()
Headers for outbound mail. List-Unsubscribe* only on signed bulk mail.
public
static buildOutboundHeaders(string $type[, mixed $unsubscribe_url = null ]) : array<int, array{Name: string, Value: string}>
Parameters
- $type : string
- $unsubscribe_url : mixed = null
Return values
array<int, array{Name: string, Value: string}>computeCheck()
public
static computeCheck(mixed $identity) : mixed
Parameters
- $identity : mixed
getBulkPacePerSecond()
public
static getBulkPacePerSecond() : int
Return values
intgetSuppressReason()
Current suppress reason for an address, or null if not suppressed.
public
static getSuppressReason(mixed $email) : string|null
Parameters
- $email : mixed
Return values
string|nullisOneClickUnsubscribeRequest()
RFC 8058 one-click body detection (no session required).
public
static isOneClickUnsubscribeRequest([mixed $post = null ][, mixed $raw_body = null ]) : bool
Parameters
- $post : mixed = null
- $raw_body : mixed = null
Return values
boolisRateLimited()
Whether a sendDetailed* result indicates SES rate limiting / throttling.
public
static isRateLimited(array<string|int, mixed> $detail) : bool
Bulk senders should stop the run after recording that recipient.
Parameters
- $detail : array<string|int, mixed>
Return values
boolisRateLimitThrowable()
Detect SES throttle / rate-limit from exception type or message text.
public
static isRateLimitThrowable(Throwable $e) : bool
Parameters
- $e : Throwable
Return values
boolisSesConfigured()
Whether SES is configured for outbound mail.
public
static isSesConfigured() : bool
Return values
boolisSuppressed()
public
static isSuppressed(mixed $email) : bool
Parameters
- $email : mixed
Return values
boolisUserOptedOut()
True when user or linked profile has subscribe = -1 (no mail).
public
static isUserOptedOut(mixed $user_id) : bool
Parameters
- $user_id : mixed
Return values
boolnormalizeEmail()
public
static normalizeEmail(mixed $email) : string
Parameters
- $email : mixed
Return values
stringoptOutSubscribeByEmail()
Set subscribe=-1 on profile and lti_user rows matching this email.
public
static optOutSubscribeByEmail(mixed $email) : void
Parameters
- $email : mixed
paceBulkSend()
Soft pace for bulk sends toward getBulkPacePerSecond() average.
public
static paceBulkSend() : void
If that many attempts fall inside a one-second window, sleep only long enough to fill out the remainder of that second, then continue. Rate 0 disables pacing. Logs (and prints on CLI). Does not stop the run.
recordSesEvent()
Append a row to mail_ses_events (audit of SES notification + action taken).
public
static recordSesEvent(array{sns_message_id?: ?string, ses_message_id?: ?string, event_type: string, event_subtype?: ?string, email?: ?string, mail_type?: ?string, action: string, detail?: ?string, payload_json?: ?string} $fields) : bool
Parameters
- $fields : array{sns_message_id?: ?string, ses_message_id?: ?string, event_type: string, event_subtype?: ?string, email?: ?string, mail_type?: ?string, action: string, detail?: ?string, payload_json?: ?string}
Return values
bool —True when inserted
replyToAddress()
Optional Reply-To for all transports (where human replies should go).
public
static replyToAddress() : string|null
Return values
string|nullsend()
public
static send(mixed $to, mixed $subject, mixed $message[, mixed $id = false ][, mixed $token = false ]) : mixed
Prefer sendTransactional() or sendBulk(). Defaults to transactional.
Parameters
- $to : mixed
- $subject : mixed
- $message : mixed
- $id : mixed = false
- $token : mixed = false
sendBulk()
Campaign / list-style mail to many recipients.
public
static sendBulk(mixed $to, mixed $subject, mixed $message[, mixed $id = false ][, mixed $token = false ]) : mixed
Returns true on success, false on failure, null when mail is disabled.
Parameters
- $to : mixed
- $subject : mixed
- $message : mixed
- $id : mixed = false
- $token : mixed = false
sendDetailed()
public
static sendDetailed(mixed $to, mixed $subject, mixed $message[, mixed $id = false ][, mixed $token = false ]) : array<string|int, mixed>
Prefer sendDetailedTransactional() or sendDetailedBulk(). Defaults to transactional.
Parameters
- $to : mixed
- $subject : mixed
- $message : mixed
- $id : mixed = false
- $token : mixed = false
Return values
array<string|int, mixed>sendDetailedBulk()
public
static sendDetailedBulk(mixed $to, mixed $subject, mixed $message[, mixed $id = false ][, mixed $token = false ]) : array<string|int, mixed>
Parameters
- $to : mixed
- $subject : mixed
- $message : mixed
- $id : mixed = false
- $token : mixed = false
Return values
array<string|int, mixed>sendDetailedTransactional()
public
static sendDetailedTransactional(mixed $to, mixed $subject, mixed $message[, mixed $id = false ][, mixed $token = false ]) : array<string|int, mixed>
Parameters
- $to : mixed
- $subject : mixed
- $message : mixed
- $id : mixed = false
- $token : mixed = false
Return values
array<string|int, mixed>sendTransactional()
One-to-one / system response mail (key approval, notices, etc.).
public
static sendTransactional(mixed $to, mixed $subject, mixed $message[, mixed $id = false ][, mixed $token = false ]) : mixed
Returns true on success, false on failure, null when mail is disabled.
Parameters
- $to : mixed
- $subject : mixed
- $message : mixed
- $id : mixed = false
- $token : mixed = false
sesEventsTableExists()
Whether the mail_ses_events table exists.
public
static sesEventsTableExists() : bool
Return values
boolsetBulkPacePerSecond()
Set local bulk pacing target (messages/sec). 0 disables pacing.
public
static setBulkPacePerSecond(mixed $per_second) : void
Parameters
- $per_second : mixed
shouldSkipSend()
Pre-send gate: skip before calling SES/mail().
public
static shouldSkipSend(mixed $email, string $type[, mixed $user_id = false ]) : bool
Parameters
- $email : mixed
- $type : string
- $user_id : mixed = false
Return values
boolsuppress()
Upsert an address into the suppress list.
public
static suppress(mixed $email, mixed $reason[, mixed $detail = null ][, mixed $message_id = null ]) : void
Parameters
- $email : mixed
- $reason : mixed
- $detail : mixed = null
- $message_id : mixed = null
suppressReasonBlocksType()
Whether this suppress reason blocks the given mail type.
public
static suppressReasonBlocksType(string|null $reason, string $type) : bool
bounce/complaint → all mail; unsubscribe → bulk only.
Parameters
- $reason : string|null
- $type : string
Return values
boolsuppressTableExists()
Whether the mail_suppress table exists.
public
static suppressTableExists() : bool
Return values
booltransport()
Active transport name when mail is enabled.
public
static transport() : "ses"|"php"
Return values
"ses"|"php"configurationSetForType()
Configuration set for this mail type (bulk can use a separate set).
private
static configurationSetForType(string $type) : string|null
Parameters
- $type : string
Return values
string|nullfromAddress()
From for all transports (SES and PHP mail()).
private
static fromAddress() : string
Return values
stringsendDetailedWithType()
private
static sendDetailedWithType(string $type, mixed $to, mixed $subject, mixed $message[, mixed $id = false ][, mixed $token = false ]) : array{success: bool, transport: string, error: ?string, message_id: ?string, disabled: bool, suppressed: bool, rate_limited: bool, type: string}
Parameters
- $type : string
- $to : mixed
- $subject : mixed
- $message : mixed
- $id : mixed = false
- $token : mixed = false
Return values
array{success: bool, transport: string, error: ?string, message_id: ?string, disabled: bool, suppressed: bool, rate_limited: bool, type: string}sendResult()
private
static sendResult(array{success: bool, disabled: bool} $detail) : bool|null
Parameters
- $detail : array{success: bool, disabled: bool}
Return values
bool|nullsendViaPhpMail()
private
static sendViaPhpMail(mixed $to, mixed $subject, mixed $msg, mixed $from, mixed $unsubscribe_url, mixed $id, mixed $token, string $type, array<string|int, mixed> $result) : array<string|int, mixed>
Parameters
- $to : mixed
- $subject : mixed
- $msg : mixed
- $from : mixed
- $unsubscribe_url : mixed
- $id : mixed
- $token : mixed
- $type : string
- $result : array<string|int, mixed>
Return values
array<string|int, mixed>sendViaSes()
private
static sendViaSes(mixed $to, mixed $subject, mixed $msg, mixed $from, mixed $unsubscribe_url, string $type, array<string|int, mixed> $result) : array<string|int, mixed>
Parameters
- $to : mixed
- $subject : mixed
- $msg : mixed
- $from : mixed
- $unsubscribe_url : mixed
- $type : string
- $result : array<string|int, mixed>
Return values
array<string|int, mixed>unsubscribeUrl()
private
static unsubscribeUrl(mixed $id, mixed $token) : string
Parameters
- $id : mixed
- $token : mixed