Expense Receipt Forwarder

{
  "last_run": "2026-01-27",
  "last_run_account": "[email protected]",
  "forwarded_message_ids": ["id1", "id2", ...]
}

Reading State

At the start of each run, read the state file if it exists:

cat ~/.claude/commands/expense-receipt-forwarder/.state.json

If the file exists and contains a valid last_run date, use that as the default start date instead of "last 7 days".

If the file doesn't exist or is invalid, fall back to last 7 days.

Writing State

After a successful run (user confirmed and receipts were forwarded), update the state file:

• Set last_run to today's date
• Set last_run_account to the Gmail account used
• Append newly forwarded message IDs to forwarded_message_ids array (keep last 500 to prevent unbounded growth)

Workflow

Step 1: Check State and Confirm Parameters

1. Read the state file to get the last run date
2. Present parameters to user:
   • Gmail account: From context or prompt
   • Date range: "Since [last_run date]" or "Last 7 days" if first run
3. Ask user to confirm or adjust

Example prompt:

"Last run was on Jan 20, 2026. Search for receipts since then in [email protected]? (Or specify a different date range)"

Step 2: Search for Receipts

Use mcp__google_workspace__search_gmail_messages to find potential receipts.

Important: Gmail's after: operator is exclusive (does not include the specified date). To include the last_run date in results, subtract one day from the date when building the query. For example, if last_run is "2026-01-30", use after:2026/01/29.

Execute these searches in sequence, collecting unique message IDs:

Search queries to run (use day before last_run for YYYY/MM/DD):
1. "subject:(receipt OR invoice OR confirmation OR payment) after:YYYY/MM/DD"
2. "from:(receipt OR billing OR invoice OR noreply OR no-reply) subject:(order OR payment OR purchase) after:YYYY/MM/DD"
3. "subject:(payment confirmed OR order confirmed OR purchase confirmed OR payment received OR payment success) after:YYYY/MM/DD"

De-duplication: Skip any message IDs that appear in forwarded_message_ids from the state file.

Step 3: Fetch and Analyze Email Content

Use mcp__google_workspace__get_gmail_messages_content_batch to retrieve email details.

Important: When fetching messages, note any attachments returned in the response. Each message may include an attachments array with:

• attachment_id: The ID needed to download the attachment
• filename: The attachment filename
• mime_type: The file type (e.g., "application/pdf", "image/png")
• size: File size in bytes

For each email, determine if it's a legitimate personal expense receipt by checking for:

• Payment amount mentioned (e.g., "$XX.XX", "Total:", "Amount:")
• Transaction/order/invoice number
• Merchant/vendor name
• Payment method reference (e.g., "Visa ending in", "PayPal")
• Date of transaction
• PDF or image attachments (receipts often have PDF attachments)

CRITICAL EXCLUSIONS - Always skip these:

Company Payment Notifications (payments TO vendors, not receipts FROM vendors):

• Subject contains: "Payment scheduled", "Payment sent", "Payment to", "Paying [vendor name]"
• Initiated by someone else (e.g., "Payment scheduled by Dan Fowler")
• Company operational payments (payroll, contractor payments, vendor payments)
• Examples to exclude:
  • "Payment scheduled by Dan Fowler to Wilson Sonsini ($3,720.00)"
  • "Contractor payment debit happening today" (payroll, not personal expense)
  • "Payroll confirmation" (company payroll, not reimbursable)

Detection: Receipt FROM vendor vs Payment TO vendor:

• ✓ Receipt FROM vendor: "Your receipt from Anthropic", "Thank you for your purchase", "Order confirmation from Amazon"
• ✗ Payment TO vendor: "Payment to Wilson Sonsini", "Payment scheduled by [person]", "We're paying [vendor]"
• ✓ Personal expense: Charged to personal card, mentions "your card ending in", "charged to your account"
• ✗ Company expense: Debiting company account, "account ending in 2386" (company account), bulk payments

Other exclusions:

• Marketing emails disguised as receipts
• Subscription renewal reminders (not actual charges)
• Shipping notifications without payment info
• Password reset or account notifications
• Thread replies/forwards (Re:, Fwd:) unless they contain actual receipts

Step 4: Classify and Forward Receipts

FIRST: Apply exclusion filters from Step 3. Skip any emails matching exclusion criteria.

Then classify remaining emails by certainty level:

High certainty (auto-forward without asking):

• ✓ Receipt FROM vendor (not payment TO vendor)
• ✓ Personal expense (not company operational payment)
• Has clear payment amount (e.g., "$XX.XX", "Total:")
• From known receipt senders (see Common Receipt Sources)
• Contains invoice/receipt number or transaction ID
• Contains payment method reference (personal card/account)
• Language indicates "you purchased", "your order", "thank you for your payment"

Low certainty (ask user first):

• Missing payment amount
• From unknown sender
• Ambiguous whether personal vs company expense
• Unclear if receipt FROM vendor or payment TO vendor

Auto-skip (don't even ask):

• Matches any exclusion criteria from Step 3
• Company payment notifications
• Payroll/contractor payments
• Payments initiated by others

Step 5: Forward Receipts with Attachments

Critical: Receipts often have PDF or image attachments that contain the actual receipt. These MUST be included when forwarding.

Use mcp__google_workspace__forward_gmail_message to forward receipts. This tool automatically preserves all attachments (PDFs, images, etc.) from the original email.

High-certainty receipts: Forward automatically and display a summary table as you forward:

| Date | From | Subject | Amount | Attachments | Status |
|------|------|---------|--------|-------------|--------|
| ... | ... | ... | ... | 1 PDF | ✓ Forwarded |

Low-certainty receipts: Present to user for confirmation before forwarding:

| Date | From | Subject | Amount (if found) | Attachments | Forward? |
|------|------|---------|-------------------|-------------|----------|
| ... | ... | ... | ... | 2 files | ? |

For each receipt to forward, use:

mcp__google_workspace__forward_gmail_message(
  user_google_email: "[email protected]",
  message_id: "[message_id_from_search]",
  to: "[email protected]"
)

Benefits of forward_gmail_message:

• Automatically preserves ALL attachments (PDFs, images, etc.)
• Maintains original formatting and email structure
• Single API call per email (no need to download attachments separately)
• Expensify SmartScan works best with PDF and image attachments, which are automatically preserved

Step 5b: Mark Forwarded Emails as Read

After successfully forwarding receipts, mark them as read to keep the inbox clean.

Use mcp__google_workspace__batch_modify_gmail_message_labels to remove the "UNREAD" label from all successfully forwarded messages:

Parameters:
- user_google_email: The Gmail account email
- message_ids: List of message IDs that were successfully forwarded
- remove_label_ids: ["UNREAD"]

This batch operation marks all forwarded receipts as read in a single API call, improving efficiency.

Step 6: Update State and Summary Report

After successful forwarding and marking as read (Step 5b):

1. Update state file with today's date and forwarded message IDs
2. Provide summary:

## Receipt Forwarding Complete

**Forwarded**: X emails (Y with attachments)
**Marked as read**: X emails
**Skipped**: Y emails (not receipts or user declined)
**State updated**: Next run will search from [today's date]

### Forwarded Receipts:
1. [Date] - [Merchant] - [Amount] - [X attachments]
2. ...

### Skipped:
1. [Reason] - [Subject]

Classification Examples

✓ FORWARD - Personal Expense Receipts:

• "Your receipt from Anthropic, PBC #2394-2870" - Personal SaaS charge
• "Amazon Web Services Invoice Available [Account: 864572276780]" - Personal AWS usage
• "RSAC 2026 Conference Registration Confirmation" - Conference ticket purchase
• "Your confirmation receipt: KRBZYX for your flight to San Francisco" - Personal travel
• "[GitHub] Payment Receipt for Certiv-ai" - Company service (reimbursable)
• "Billing Receipt - January 2026" from Expensify - SaaS subscription
• "Your receipt from Quo #2943-1418" - Vendor receipt

✗ SKIP - Company Payment Notifications:

• "Payment scheduled by Dan Fowler to Wilson Sonsini ($3,720.00)" - Company paying vendor
• "Contractor payment debit happening today for Certiv, Inc." - Company payroll
• "Certiv, Inc.: Fri, Feb 13 payroll confirmation" - Company payroll processing
• "Certiv, Inc.'s January 2026 invoice has been paid" - Company service invoice (not personal)

? ASK USER - Ambiguous Cases:

• "Invoice from Afanasev Mehanig Solutions" - Contractor invoice (could be reimbursable consulting)
• "Invoice for the 3rd pack of 20h" - Consultant hours (need context)
• "Mike Invoice" - Internal discussion about invoice (not actual receipt)

Common Receipt Sources

These senders commonly send legitimate personal receipts:

• Amazon, Apple, Google, Microsoft
• Airlines (United, Delta, Alaska, etc.)
• Hotels (Marriott, Hilton, etc.)
• Ride services (Uber, Lyft)
• Food delivery (DoorDash, Uber Eats, Grubhub)
• SaaS providers (AWS, Anthropic, OpenAI, GitHub, etc.)
• Payment processors (PayPal, Stripe, Square)
• Restaurants and retailers

Error Handling

• If Gmail rate limited, wait and retry with smaller batches
• If forwarding fails, log the error and continue with remaining emails
• forward_gmail_message automatically handles attachment downloading and inclusion
• Only update state file if at least one receipt was successfully forwarded
• Report any failures in the final summary