feat: add email handler — send and fetch emails

[chubes4]

Summary

• Adds email send (publish handler) and email fetch (IMAP inbox) to Data Machine core
• Follows the abilities-first pattern: Ability → Handler → AI Tool
• Both send and fetch work through the WordPress Abilities API from day 1 — callable from REST, CLI, chat, and pipelines

Architecture

SendEmailAbility (datamachine/send-email)
  ↑ Email Publish Handler (email_publish)
    ↑ AI Tool: email_send

FetchEmailAbility (datamachine/fetch-email)
  ↑ Email Fetch Handler (email)
    ↑ IMAP Auth Provider (email_imap)

Send Side

Component	File	Purpose
SendEmailAbility	inc/Abilities/Publish/SendEmailAbility.php	Core logic: wp_mail() with attachments, headers, placeholder replacement
Email handler	inc/Core/Steps/Publish/Handlers/Email/Email.php	Pipeline handler: merges config defaults with AI params, delegates to ability
EmailSettings	inc/Core/Steps/Publish/Handlers/Email/EmailSettings.php	8 configurable fields: to/cc/bcc, from name/email, reply-to, subject, content type

AI Tool: email_send — LLM composes subject + body (HTML), optionally overrides recipients and attaches files

Placeholders: {month}, {year}, {site_name}, {date}, {admin_email} in subject and body

Transport: Uses wp_mail() — respects FluentSMTP, WP Mail SMTP, or any mail plugin the site has configured

Fetch Side

Component	File	Purpose
FetchEmailAbility	inc/Abilities/Fetch/FetchEmailAbility.php	Core logic: IMAP connection, search, body parsing, attachment download
Email handler	inc/Core/Steps/Fetch/Handlers/Email/Email.php	Pipeline handler: resolves IMAP creds from auth, builds search criteria
EmailAuth	inc/Core/Steps/Fetch/Handlers/Email/EmailAuth.php	IMAP credential storage via BaseAuthProvider
EmailFetchSettings	inc/Core/Steps/Fetch/Handlers/Email/EmailFetchSettings.php	10 fields: folder, search, from/subject filters, mark as read, download attachments

Dedup: Uses RFC 2822 Message-ID header as dedup_key — standard DM processed items system

Body parsing: Prefers text/plain, falls back to stripped text/html. Handles multipart/alternative and nested parts.

IMAP search: Supports standard IMAP criteria (UNSEEN, ALL, FROM "x", SINCE "date") augmented by handler config filters

Pipeline Patterns Enabled

# Content digest
RSS Fetch → AI (summarize) → Email Publish (weekly digest)

# Inbox triage
Email Fetch (UNSEEN) → AI (classify) → Email Publish (auto-reply)

# Report delivery
WP Posts Fetch → AI (analyze) → Email Publish (send report)

Testing

Tested on chubes.net via WP-CLI:

• ✅ Both abilities registered (wp_get_ability())
• ✅ Both handlers registered (datamachine_handlers filter)
• ✅ Settings fields returned (8 publish, 10 fetch)
• ✅ Auth provider registered (email_imap)
• ✅ AI tool registered (email_send)
• ✅ Email sent successfully with placeholder resolution

Closes #341

[github-actions]

Homeboy Results — data-machine

Lint

⚡ Scope: changed files only

✅ lint (changed files only)

Test

⚡ Scope: changed files only

✅ test (changed files only)

Audit

⚡ Scope: changed files only

✅ audit (changed files only)

Tooling versions

• Homeboy CLI: homeboy 0.79.0+04e914f6
• Extension: wordpress from https://github.com/Extra-Chill/homeboy-extensions
• Extension revision: unknown
• Action: Extra-Chill/homeboy-action@v1

---

Homeboy Action v1