← Back to blog

Pull invoices and receipts from email attachments with an agent

guidesclaude-code

Month-end usually means searching your inbox for invoices, downloading each PDF, and typing the totals into a spreadsheet. The searching and typing are exactly what an agent is good at. The part to be careful with is access: the agent needs to read your mail, but it never needs to send or change any of it.

This guide sets up Claude Code to find invoice and receipt emails, save the attachments to a folder, and write a CSV with the vendor, date, invoice number, and total for each one. It uses Fluxmail, a self-hosted server that connects Claude Code to Gmail, Outlook, and IMAP mailboxes.

1. Connect your mailbox read-only

Follow the quickstart to install Fluxmail and connect a mailbox. Then add it to Claude Code with the read-only profile:

claude mcp add fluxmail -- fluxmail stdio --profile read-only

Read-only is all this job needs. Claude Code can search, open messages, and download attachments, and nothing else.

2. Find the invoice emails

Make a working folder, start Claude Code in it, and ask:

Find emails with attachments from September 2026 that look like invoices or receipts. List the sender, subject, date, and attachment names. Don't download anything yet.

Claude Code searches with Fluxmail's search_emails tool. Fluxmail's search terms are combined with AND, so Claude runs a few narrow searches instead of one broad one:

has:attachment subject:invoice after:2026-09-01 before:2026-10-01
has:attachment subject:receipt after:2026-09-01 before:2026-10-01
has:attachment from:billing after:2026-09-01 before:2026-10-01

Check the list. Vendors name their emails in odd ways, so tell Claude about any that are missing: "Also include anything from AWS and anything with 'statement' in the subject."

If you use Gmail, you can use Gmail's own search syntax for broader queries. Ask Claude to use a Gmail search such as has:attachment {invoice receipt statement} after:2026/09/01. Fluxmail passes Gmail syntax through when the search targets a single Gmail account.

3. Download the attachments

Claude Code can read PDFs, but first they need to be on disk. The Fluxmail CLI downloads an attachment to a path you choose:

fluxmail attachments download <message-id> <attachment-id> --output ./invoices/aws-2026-09.pdf

Ask Claude Code to run that command for each attachment on the list. It gets the message and attachment IDs from the messages it opened with get_email. Claude Code asks before running each shell command, so you can see every download before it happens.

To skip the prompt for downloads only, allow that one command in .claude/settings.json in your working folder:

{
  "permissions": {
    "allow": ["Bash(fluxmail attachments download *)"]
  }
}

Only fluxmail attachments download runs without asking. Any other command, including other fluxmail commands, still needs your approval.

Fluxmail will not overwrite an existing file unless you pass --force, so running the job twice does not clobber earlier downloads.

4. Extract the fields

With the PDFs saved, ask:

Read every PDF in ./invoices. For each, extract vendor, invoice number, invoice date, due date, currency, subtotal, tax, and total. Write the results to invoices.csv, one row per invoice. If a field is missing or unclear, leave it blank and add a note column. Don't guess.

Claude Code reads each file and writes the CSV. Open it next to the PDFs and spot-check a few rows, especially totals and currencies. Models read clean invoice PDFs well, but scanned or unusual layouts cause mistakes, and "leave it blank" catches more of them than a confident guess.

Some vendors put the invoice in the email body and attach nothing. Ask Claude to read those messages with get_email and add them to the CSV with a note that there was no attachment.

5. Save it as a skill

Make the routine repeatable with a Claude Code skill. Create ~/.claude/skills/collect-invoices/SKILL.md:

---
name: collect-invoices
description: Find invoice and receipt emails for a month, download the attachments, and write invoices.csv.
---

Ask me which month to collect if I did not say.

1. Search for emails with attachments in that month whose subject or sender
   suggests an invoice, receipt, or statement. Include AWS, Google Workspace,
   and anything from a billing@ address.
2. Show me the list and wait for my OK.
3. Download each attachment to ./invoices/ with
   `fluxmail attachments download`, named vendor-YYYY-MM.pdf.
4. Extract vendor, invoice number, dates, currency, subtotal, tax, and total
   into invoices.csv. Leave unclear fields blank and explain in a notes column.
5. Finish with the grand total per currency and a list of anything you skipped.

Next month, run /collect-invoices September from your working folder.

Why read-only matters here

Invoice emails come from outside your organization, and fake invoices are a common phishing tactic. An agent that reads them should not be able to reply to them or forward anything, whatever instructions they contain. With the read-only profile, the worst a malicious email can do is put a wrong number in your CSV, which your spot check catches. How to give an AI agent access to your email safely covers the rest.