#+TITLE: Email Workflow
#+AUTHOR: Craig Jennings & Claude
#+DATE: 2026-01-26

* Overview

This workflow sends emails with optional attachments via =cmail-action send= (the cmail account, c@cjennings.net via Proton Bridge).

* When to Use This Workflow

When Craig says:
- "email workflow" or "send an email"
- "email [person] about [topic]"
- "send [file] to [person]"

* Required Information

Before sending, gather and confirm:

1. **To:** (required) - recipient email address(es)
2. **CC:** (optional) - carbon copy recipients
3. **BCC:** (optional) - blind carbon copy recipients
4. **Subject:** (required) - email subject line
5. **Body:** (required) - email body text
6. **Attachments:** (optional) - file path(s) to attach

* The Workflow

** Step 1: Gather Missing Information

If any required fields are missing, prompt Craig:

#+begin_example
To send this email, I need:
- To: [who should receive this?]
- Subject: [what's the subject line?]
- Body: [what should the email say?]
- Attachments: [any files to attach?]
- CC/BCC: [anyone to copy?]
#+end_example

** Step 2: Validate Email Addresses

Look up all recipient names/emails in the contacts file:

#+begin_src bash
grep -i "[name or email]" ~/sync/org/contacts.org
#+end_src

**Note:** If contacts.org is empty, check for sync-conflict files:
#+begin_src bash
ls ~/sync/org/contacts*.org
#+end_src

For each recipient:
1. Search contacts by name or email
2. Confirm the email address matches
3. If name not found, ask Craig to confirm the email is correct
4. If multiple emails for a contact, ask which one to use

** Step 3: Confirm Before Sending

Display the complete email for review:

#+begin_example
Ready to send:

From: c@cjennings.net
To: [validated email(s)]
CC: [if any]
BCC: [if any]
Subject: [subject]

[body text]

Attachments: [list files if any]

Send this email? [Y/n]
#+end_example

** Step 4: Send the Email

Send with =cmail-action send=. It builds the MIME message, threading, and attachments, and connects to Proton Bridge's local SMTP as c@cjennings.net. Don't hand-roll a heredoc or pipe through =msmtp=.

#+begin_src bash
# simple
cmail-action send --to addr@example.com --subject "Subject" --body "One-liner body."
# multi-line body from a file (preferred for anything beyond one line)
cmail-action send --to addr@example.com --subject "Subject" --body-file /tmp/draft.txt
# attachments (repeatable --attach, MIME type auto-detected)
cmail-action send --to addr@example.com --subject "Subj" --body-file /tmp/draft.txt \
  --attach report.pdf --attach chart.png
# Cc / Bcc (repeatable) and a threaded reply
cmail-action send --to addr@example.com --subject "Re: ..." --body-file /tmp/draft.txt \
  --cc colleague@example.com --bcc archive@example.com \
  --in-reply-to "<original-msgid>" --references "<root-msgid> <original-msgid>"
#+end_src

=--cc= / =--bcc= are repeatable; recipients are derived from the To/Cc/Bcc headers automatically, and Bcc is stripped from the sent message. For a reply that threads on the recipient's end, pass =--in-reply-to= (and =--references=) with the original message's Message-ID.

** Step 5: Verify Delivery

Check the msmtp log for confirmation:

#+begin_src bash
tail -3 ~/.msmtp.cmail.log
#+end_src

Look for: ~smtpstatus=250~ and ~exitcode=EX_OK~

** Step 6: Sync to Sent Folder (Optional)

If Craig wants the email in his Sent folder:

#+begin_src bash
mbsync cmail
#+end_src

* msmtp Configuration

The cmail account should be configured in ~/.msmtprc:

#+begin_example
account cmail
tls_certcheck off
auth on
host 127.0.0.1
port 1025
protocol smtp
from c@cjennings.net
user c@cjennings.net
passwordeval "cat ~/.config/.cmailpass"
tls on
tls_starttls on
logfile ~/.msmtp.cmail.log
#+end_example

**Note:** ~tls_certcheck off~ is used because Proton Bridge uses self-signed certificates on localhost.

* Attachment Handling

** Supported Types

Common MIME subtypes:
- PDF: ~_subtype='pdf'~
- Images: ~_subtype='png'~, ~_subtype='jpeg'~
- Text: ~_subtype='plain'~
- Generic: ~_subtype='octet-stream'~

** Multiple Attachments

Add multiple attachment blocks before ~print(msg.as_string())~

* Troubleshooting

** Password File Missing
Ensure ~/.config/.cmailpass exists with the Proton Bridge SMTP password.

** TLS Certificate Errors
Use ~tls_certcheck off~ in msmtprc for Proton Bridge (localhost only).

** Proton Bridge Not Running
Start Proton Bridge before sending. Check if port 1025 is listening:
#+begin_src bash
ss -tlnp | grep 1025
#+end_src

* Example Usage

Craig: "email workflow - send the November 3rd SOV to Christine"

Claude:
1. Searches contacts for "Christine" -> finds cciarmello@gmail.com
2. Asks for subject and body if not provided
3. Locates the SOV file in assets/
4. Shows confirmation
5. Sends via msmtp
6. Verifies delivery in log