Implementation: inc/Api/Email.php

Base URL: /wp-json/datamachine/v1/email

Overview

Email endpoints expose Data Machine email abilities over REST for sending mail, reading IMAP inboxes, replying, moving, flagging, deleting, unsubscribing, and testing the stored IMAP connection.

Authentication

All email routes require Data Machine manage permission via PermissionHelper::can_manage().

PermissionHelper::can_manage() passes when the caller has manage_flows, manage_settings, or manage_agents. Administrators also pass through the manage_options fallback built into PermissionHelper.

External REST clients should use WordPress application passwords or cookie auth. Inbox operations also require a configured email_imap auth provider; missing IMAP credentials return not_configured with HTTP 400.

Route Table

Core Parameters

Send And Reply

Fetch And Message Operations

Response Shape

Email endpoints return ability-native success objects. Failed ability results are normalized to an email_error REST error with HTTP 400.

Send response shape:

{
  "success": true,
  "message": "Email sent successfully",
  "recipients": ["[email protected]"],
  "subject": "Weekly report",
  "logs": []
}

Fetch response shape:

{
  "success": true,
  "data": {
    "items": [],
    "count": 10,
    "total_matches": 42,
    "offset": 0,
    "has_more": true
  },
  "logs": []
}

Batch operation response shapes include counters such as moved_count, flagged_count, deleted_count, unsubscribed, failed, or no_header depending on the route.

Agent Usage Examples

List unread message headers without marking them read:

curl "https://example.com/wp-json/datamachine/v1/email/fetch?search=UNSEEN&headers_only=1&max=20" 
  -u username:application_password

Move GitHub notifications to an archive folder:

curl -X POST https://example.com/wp-json/datamachine/v1/email/batch/move 
  -H "Content-Type: application/json" 
  -u username:application_password 
  -d '{"search":"FROM "github.com"","destination":"Archive","max":100}'

Send a concise agent report:

curl -X POST https://example.com/wp-json/datamachine/v1/email/send 
  -H "Content-Type: application/json" 
  -u username:application_password 
  -d '{"to":"[email protected]","subject":"Daily agent summary","body":"<p>No blockers.</p>"}'