Blog

Pull invoices and receipts from email attachments with an agent

Have Claude Code find invoice emails, download the PDFs, and build a spreadsheet of vendors, dates, and totals. The agent only gets read access to your mail.

Richard Chu

Fluxmail Founder

5 min read

Updated

Receipts rising out of an open envelope held by a paperclip

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 Cloud, a hosted MCP server that connects Claude Code to Gmail, Outlook, and IMAP mailboxes. Claude Code finds and reads the emails over MCP, and a read-only agent key lets it save the PDFs to a folder.

1. Connect your mailbox read-only

Follow the Cloud quickstart to create an account and connect a mailbox. Then add Fluxmail to Claude Code with read access only:

claude mcp add-json --scope user fluxmail-cloud '{"type":"http","url":"https://cloud.fluxmail.ai/mcp?scopes=mail.read","oauth":{"scopes":"mail.read offline_access"}}'
claude mcp login fluxmail-cloud

The second command opens Fluxmail in your browser, where you pick the mailbox and approve. Read-only is all this job needs. Claude Code can search, open messages, and download attachments. If you already added fluxmail-cloud with other permissions, remove it with claude mcp remove fluxmail-cloud and revoke the old connection under Connections first.

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 an attachment through MCP, but for month-end you probably want the PDFs saved in a folder you can keep. Fluxmail's REST API returns an attachment as a file, so curl can save it to a path you choose.

Create a key in Agent keys with the Read only preset and the same mailbox. Cloud shows the key once. Set it in your shell before you start Claude Code, and keep it out of files in your working folder:

export FLUXMAIL_CLOUD_AGENT_KEY='paste-the-key-here'

Then ask Claude Code to download each attachment on the list with a command like this:

curl --fail-with-body https://cloud.fluxmail.ai/api/mail/download_attachment \
  --header "Authorization: Bearer $FLUXMAIL_CLOUD_AGENT_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"accountId":"MAILBOX_ID","messageId":"MESSAGE_ID","attachmentId":"ATTACHMENT_ID"}' \
  --create-dirs --output ./invoices/aws-2026-09.pdf.part \
  && mv ./invoices/aws-2026-09.pdf.part ./invoices/aws-2026-09.pdf

Claude Code gets the mailbox, message, and attachment IDs from the messages it opened with get_email. If a download fails, curl writes the error to the .part file and stops before mv, so a failed rerun never replaces a PDF you already saved. Ask Claude Code to skip any invoice that already has a file in ./invoices.

Claude Code asks before running each shell command, so you see every download before it happens. Keep that prompt for curl. An allow rule would also let a crafted email persuade Claude Code to send your key or local files to another address without asking you.

If you run self-hosted Fluxmail instead, add it to Claude Code with claude mcp add fluxmail -- fluxmail stdio --profile read-only and download with fluxmail attachments download <message-id> <attachment-id> --output ./invoices/aws-2026-09.pdf. The CLI won't overwrite an existing file unless you pass --force.

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/, named vendor-YYYY-MM-DD.pdf,
   with `curl --fail-with-body` to
   https://cloud.fluxmail.ai/api/mail/download_attachment using
   $FLUXMAIL_CLOUD_AGENT_KEY. Save to a .part file and rename it only if
   curl succeeds. Skip invoices that already have a file.
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.

At the start of each month, run it from your working folder with the month that just ended, such as /collect-invoices October in early November.

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 read-only access, 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.

Try Fluxmail Cloud

Connect your AI agent to your Gmail, Outlook, or IMAP email accounts.