smtp-send: optional IMAP APPEND to populate Sent folder

[omarshahine]

Problem

Messages sent via mail-cli smtp-send hand off to the SMTP relay and are never APPENDed to the user's Sent folder. As a result:

• The message does not appear in Mail.app's Sent view, iCloud.com web Sent view, or any other IMAP-indexed Sent folder
• There is no client-side audit trail for scheduled / cron / agent sends
• Users who switch from mail-cli send (AppleScript, populates Sent automatically) to smtp-send lose that affordance

Currently a stderr note is emitted at send time to warn about this, and the README calls it out under Known Limitations. But the real fix is to actually APPEND.

Proposed approach

Add an --imap-append-sent flag (default-on when sending via iCloud, default-off otherwise) that, after a successful SMTP delivery, opens a separate IMAP-over-TLS connection and APPENDs the rendered RFC 5322 message to the Sent folder.

iCloud IMAP endpoint: imap.mail.me.com:993 (implicit TLS).

State machine is small:

1. Connect (implicit TLS via NWConnection)
2. A1 LOGIN <user> <password>
3. A2 APPEND "Sent Messages" (\Seen) {LENGTH}
4. Server responds + go ahead
5. Send the raw message bytes + CRLF
6. Read A2 OK APPEND completed
7. A3 LOGOUT

Folder-name gotchas: iCloud uses "Sent Messages" (with the space); Gmail uses "[Gmail]/Sent Mail"; generic IMAP uses "Sent". Config needs a imap.sent_folder field with per-server defaults and a CLI override.

Config additions

{
  "imap": {
    "host": "imap.mail.me.com",
    "port": 993,
    "sent_folder": "Sent Messages",
    "username": "me@icloud.com",
    "secret_key": "imap.icloud.password"
  }
}

Omit → skip APPEND (current behavior). --imap-append-sent flag overrides config.

A reasonable heuristic for the default: if SMTP host ends in .mail.me.com, default-on with iCloud settings; else default-off until the user configures IMAP.

Acceptance criteria

• After mail-cli smtp-send --imap-append-sent ..., the message appears in iCloud Sent Messages both via IMAP and in Mail.app on macOS
• APPEND failures do NOT fail the send: the message was successfully delivered by SMTP, so APPEND-errors surface as a non-fatal warning (stderr + "imap_append": {"success": false, "error": "..."} field in the JSON result)
• Works with same credential store (~/.openclaw/secrets.json / ~/.config/apple-pim/secrets.json via JSON pointer)
• Test with FakeTransport: scripted IMAP APPEND conversation (tagged commands, literal-size parsing, APPEND OK)

Implementation notes

• This is arguably bigger than STARTTLS — IMAP has its own tagged-command machinery, literal size syntax, folder-naming conventions. Plan on ~300-400 lines of new code in an IMAPClient.swift.
• Consider whether to use APPEND with LITERAL+ extension (some servers support it, saves one round-trip). Start without it.
• Internal date: APPEND accepts an optional date-time argument. Use the message's Date: header value so the Sent-folder timestamp matches.