feat: Add Transactional_Email_Capability interface and Amazon SES core integration

[superdav42]

Summary

Add a new capability interface for transactional email delivery (distinct from the existing Email_Selling_Capability which provisions mailboxes). This enables the core plugin to manage how WordPress sends outbound email (password resets, WooCommerce notifications, admin alerts) on a per-site basis, with automatic domain verification.

Problem

Currently, transactional email delivery is configured at the server level (ssmtp/Postfix) and is invisible to the multisite platform. This creates several problems:

1. From-address mismatch: All sites send from the server's configured address, not their own domain -- hurting deliverability and brand trust
2. No domain verification automation: Adding a new site requires manual DNS record setup for SPF/DKIM
3. No per-site sending control: Can't throttle, monitor, or disable sending per site
4. Provider lock-in: Changing email providers requires server-level reconfiguration

Proposed Solution

1. New Transactional_Email_Capability interface

Location: inc/integrations/capabilities/interface-transactional-email-capability.php

This is a separate concern from Email_Selling_Capability (which provisions mailboxes). Transactional email is about delivery routing, not mailbox management.

interface Transactional_Email_Capability {
    public function verify_domain(string $domain): array;
    public function get_domain_verification_status(string $domain): array;
    public function get_domain_dns_records(string $domain): array;
    public function send_email(string $from, string $to, string $subject, string $body, array $headers = []): array;
    public function get_sending_statistics(string $domain, string $period = '24h'): array;
    public function set_sending_quota(string $domain, int $max_per_day): array;
    public function test_connection();
}

2. Hook into wp_mail per site

The core should provide a filter/action system that allows the active transactional email provider to intercept wp_mail() calls and route them through the configured provider, using the correct from-address for the current site's domain.

3. Domain lifecycle hooks

Fire events when domains are added/removed from the multisite so addons (email, domain seller) can react:

• wu_domain_added -- trigger domain verification in SES
• wu_domain_removed -- optionally clean up verified identity
• wu_domain_verified -- domain DNS records confirmed

4. Settings UI

Admin settings page section for selecting and configuring the transactional email provider, similar to how host provider integrations work today.

Architecture Notes

• The existing Integration base class and Integration_Registry should be reused
• AWS SigV4 signing already exists in the WorkMail integration (Amazon_WorkMail_Integration::sign_request()) -- extract to a shared AWS_Signer trait or utility class for reuse by SES
• The DNS_Provider_Interface in inc/integrations/host-providers/ can be leveraged to auto-create verification DNS records when the domain's DNS is managed by a supported provider (e.g., Cloudflare)

Acceptance Criteria

• Transactional_Email_Capability interface defined with methods above
• Domain lifecycle hooks (wu_domain_added, wu_domain_removed, wu_domain_verified) firing at appropriate points
• wp_mail interception mechanism that routes through the active provider with correct from-address
• Settings UI for provider selection and configuration
• AWS SigV4 signing extracted to reusable utility (shared with WorkMail)
• Documentation for addon developers to implement the interface

Related

• Email addon: will implement Amazon_SES_Email_Selling (separate issue)
• Domain seller addon: will hook wu_domain_added to auto-verify (separate issue)
• Existing: Email_Selling_Capability (mailbox provisioning -- different concern)
• Existing: DNS_Provider_Interface (can auto-create DNS records)

---

aidevops.sh v3.5.539 plugin for OpenCode v1.3.12 with claude-opus-4-6 in an interactive session.

[superdav42]

DISPATCH_CLAIM nonce=5673fe1308e97ae40fda410d13978ad6 runner=superdav42 ts=2026-04-01T01:21:30Z max_age_s=120

[superdav42]

PR #724 has all CI checks passing but has 1 unresolved CodeRabbit suggestion (unused $dkim_records variable). Dispatching a worker to address the review suggestion before merge.

---

aidevops.sh v3.5.540 plugin for OpenCode v1.3.0 with claude-sonnet-4-6 spent 14m and 9,376 tokens on this as a headless worker. Overall, 43m since this issue was created.

[superdav42]

Dispatching worker to address CodeRabbit review suggestion on PR #724.

• Branch: feature/723-transactional-email-capability
• Scope: Remove unused $dkim_records variable flagged by CodeRabbit in PR GH#723: Add Transactional_Email_Capability interface and Amazon SES core integration #724
• Attempt: 2 of 2 (prior worker created PR but left unresolved suggestion)
• Direction: Fix the unused variable in the SES verification code, push to the existing branch, then merge PR GH#723: Add Transactional_Email_Capability interface and Amazon SES core integration #724

---

aidevops.sh v3.5.540 plugin for OpenCode v1.3.0 with claude-sonnet-4-6 spent 15m and 10,899 tokens on this as a headless worker. Overall, 44m since this issue was created.

[superdav42]

Worker addressed the first CodeRabbit suggestion (unused $dkim_records variable) but CodeRabbit found a new issue on the updated commit: dead do_action('wu_settings_transactional_email') hook in class-settings.php line 1640 — no callbacks registered. Dispatching worker to fix this remaining suggestion.

• Branch: feature/723-transactional-email-capability
• Scope: Fix dead do_action hook or register a callback for it in the provider's register_hooks()
• Attempt: 3 of 3

[superdav42]

Worker Watchdog Kill

Reason: Worker process became idle (CPU below 5% for 300s) — likely completed or hit the OpenCode idle-state bug.

Runtime: 29m 51s

Diagnostic tail: session="Issue #723: Fix PR #724 dead do_action hook"; recent_messages=0; newest_part_age=0s; tail=text:""/full-loop Fix the remaining CodeRabbit review suggestion on PR #724 (https://github.com/Ultimate-Multisite/ultimate..." > step-start > tool:task(running) "Full loop fix PR #724"

This issue has been re-labeled status:available for re-dispatch. The next pulse or manual dispatch will pick it up.

Retry guidance: Post a blocker update describing a changed plan (or newly unblocked dependency), then move the issue back to status:available before re-dispatch.

Automated by worker-watchdog.sh (t1419)

[superdav42]

Worker Watchdog Kill

Reason: Worker process became idle (CPU below 5% for 300s) — likely completed or hit the OpenCode idle-state bug.

Runtime: 29m 51s

Diagnostic tail: session="Issue #723: Fix PR #724 dead do_action hook"; recent_messages=0; newest_part_age=0s; tail=text:""/full-loop Fix the remaining CodeRabbit review suggestion on PR #724 (https://github.com/Ultimate-Multisite/ultimate..." > step-start > tool:task(running) "Full loop fix PR #724"

This issue has been re-labeled status:available for re-dispatch. The next pulse or manual dispatch will pick it up.

Retry guidance: Post a blocker update describing a changed plan (or newly unblocked dependency), then move the issue back to status:available before re-dispatch.

Automated by worker-watchdog.sh (t1419)

[superdav42]

Worker Watchdog Kill

Reason: Worker process became idle (CPU below 5% for 300s) — likely completed or hit the OpenCode idle-state bug.

Runtime: 29m 51s

Diagnostic tail: session="Issue #723: Fix PR #724 dead do_action hook"; recent_messages=0; newest_part_age=0s; tail=text:""/full-loop Fix the remaining CodeRabbit review suggestion on PR #724 (https://github.com/Ultimate-Multisite/ultimate..." > step-start > tool:task(running) "Full loop fix PR #724"

This issue has been re-labeled status:available for re-dispatch. The next pulse or manual dispatch will pick it up.

Retry guidance: Post a blocker update describing a changed plan (or newly unblocked dependency), then move the issue back to status:available before re-dispatch.

Automated by worker-watchdog.sh (t1419)

[superdav42]

Worker Watchdog Kill — Re-dispatch (Attempt 4, Escalated to Opus)

Reason: Worker killed by watchdog after 29m 51s with 0 commits — OpenCode idle-state bug (worker likely completed analysis but process appeared idle).

Escalation: 3 failed attempts → escalating to opus tier per model escalation policy.

Previous attempts summary:

• Attempt 1: Removed unused $dkim_records variable (committed, pushed)
• Attempt 2: CodeRabbit found new issue — dead do_action('wu_settings_transactional_email') hook
• Attempt 3: Watchdog kill, 0 commits

Task: Fix dead do_action('wu_settings_transactional_email') hook in inc/class-settings.php line 1640. Either remove the do_action call or add an add_action registration in the SES provider's register_hooks() method. Push to branch feature/723-transactional-email-capability.

• Model: anthropic/claude-opus-4-6
• Attempt: 4 of 4 (escalated to opus after 3 failed sonnet attempts)
• Branch: feature/723-transactional-email-capability

---

aidevops.sh v3.5.543 plugin for OpenCode v1.3.0 with claude-sonnet-4-6 spent 23m and 15,888 tokens on this as a headless worker. Overall, 1h 29m since this issue was created.

[superdav42]

DISPATCH_CLAIM nonce=03f2d77758ad1e524c962efc81833cad runner=superdav42 ts=2026-04-01T02:30:39Z max_age_s=120