Finance inbox (mailbox scanner)

/finance/inbox watches one or more shared mailboxes (e.g., finance.india@yourdomain.com), pulls every new message, and uses Claude Sonnet to extract the financial data — vendor name, amount, currency, date, doc type — from the body and attached PDFs. You review and approve; on approve, the amount auto-posts to the entity's monthly snapshot.

Setup (one-time)

1. Connect M365 at /admin/integrations/outlook — the OAuth flow now requests Mail.Read.Shared scope. Existing connections need to re-consent (just re-click "Connect").
2. Grant shared-mailbox access in Exchange admin: the connecting user needs delegated permission ("Mailbox delegation → Read and manage") on each shared mailbox you want to scan.
3. Configure mailboxes at /finance/inbox/config — add each mailbox address. Optionally route a mailbox to a specific entity (e.g., finance.india@… → India entity).

Workflow

1. Cron polls every 15 min (POST /api/cron/finance-inbox-poll with X-OtiumWork-Cron-Token). Or click Poll now manually.
2. New messages land in /finance/inbox with status pending.
3. Click a message → click ✨ Run AI extraction. Claude Sonnet reads body + PDF attachments and returns: doc_type, vendor, amount, currency, date, confidence, reasoning.
4. Review the extracted fields. Edit any value if the AI got it wrong.
5. Click Approve & post to snapshot — amount converts to USD using your FX rates and posts to the right monthly snapshot: - vendor_bill, expense_receipt, payroll → adds to expenses - customer_invoice_paid → adds to revenue - customer_invoice_sent → adds to ar_balance - bank_statement, other → no auto-post
6. The original email is marked approved with a note like snapshot:42:expenses+=12500.

What the AI extracts

{
  "doc_type": "vendor_bill",
  "vendor_or_customer": "Acme Cloud Services",
  "amount": 1250.00,
  "currency": "USD",
  "doc_date": "2026-04-15",
  "due_date": "2026-05-15",
  "invoice_or_ref_number": "INV-2026-04-1057",
  "summary": "Acme Cloud Services monthly hosting bill, $1,250 USD, due May 15.",
  "confidence": "high",
  "reasoning": "PDF letterhead, due date stamp, and total line clearly identify this as a vendor bill."
}

Cost & accuracy

• Per-extraction cost: ~$0.05–$0.10 (PDFs are pricey — Claude Sonnet vision)
• Accuracy: ~85-90% on typical vendor invoices. Always human-review before approving.
• Re-extraction is a button click — easy to retry if the first pass fails.

What's not in V1

• No auto-approve (mandatory human review)
• No email reply / send-from
• No vendor/customer entity creation (just stores name as text)
• No matching to existing AR invoices for payment confirmations
• IMAP fallback for non-M365 mailboxes (Microsoft Graph only)

Cron setup (production)

Add a cron job (e.g., systemd timer or external scheduler) hitting:

POST https://otiumwork.com/api/cron/finance-inbox-poll
Header: X-OtiumWork-Cron-Token: <CRON_TOKEN env value>

Every 10–15 min is plenty.