Tsugi

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_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
string

buildOutboundHeaders()

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
int

getSuppressReason()

Current suppress reason for an address, or null if not suppressed.

public static getSuppressReason(mixed $email) : string|null
Parameters
$email : mixed
Return values
string|null

isOneClickUnsubscribeRequest()

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
bool

isRateLimited()

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
bool

isRateLimitThrowable()

Detect SES throttle / rate-limit from exception type or message text.

public static isRateLimitThrowable(Throwable $e) : bool
Parameters
$e : Throwable
Return values
bool

isSesConfigured()

Whether SES is configured for outbound mail.

public static isSesConfigured() : bool
Return values
bool

isSuppressed()

public static isSuppressed(mixed $email) : bool
Parameters
$email : mixed
Return values
bool

isUserOptedOut()

True when user or linked profile has subscribe = -1 (no mail).

public static isUserOptedOut(mixed $user_id) : bool
Parameters
$user_id : mixed
Return values
bool

normalizeEmail()

public static normalizeEmail(mixed $email) : string
Parameters
$email : mixed
Return values
string

optOutSubscribeByEmail()

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|null

send()

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
bool

setBulkPacePerSecond()

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
bool

suppress()

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
bool

suppressTableExists()

Whether the mail_suppress table exists.

public static suppressTableExists() : bool
Return values
bool

transport()

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|null

fromAddress()

From for all transports (SES and PHP mail()).

private static fromAddress() : string
Return values
string

sendDetailedWithType()

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|null

sendViaPhpMail()

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
Return values
string

        
On this page

Search results