How to automatically extract invoices from Gmail and Outlook into a spreadsheet
Every SaaS subscription, contractor and supplier sends an invoice, and most of them arrive as a PDF attached to an email. At the end of the month someone has to find them all, open each one, type the vendor, date, invoice number and total into a spreadsheet, and save the PDFs somewhere the accountant can get them. It's an hour of copy and paste that's easy to get wrong, and easy to miss one.
This guide automates that. It builds a tool that looks at every PDF and image attached to your emails from the last month and works out which ones are invoices or receipts. You download two files:
invoices.csv: one row per invoice, with invoice date, vendor, invoice number, total, tax, subtotal, currency, due date, who it's billed to, and the email it came in.invoices.zip: every invoice PDF, renamed so they sort by date and say whose they are (2026-11-03 Acme Ltd INV-1042.pdf), with the CSV inside.
It works on Gmail or Outlook. Once it's deployed, anyone on your team can run it on their own inbox from a form, with no subscription to yet another invoice app.
The complete code is in the Callables cookbook on GitHub, in the invoices/ folder plus a few lines each in providers/google/gmail/ and providers/microsoft/outlook/. Pick your mail provider, and this page follows:
You'll use the Gmail API to search your mail and download each email with its attachments.
You'll use Microsoft Graph to search every folder of your Microsoft 365 mailbox and download each email with its attachments.
Why rules don't work and an LLM does
The obvious approach is to pull the text out of each PDF and search it for "Invoice #" and "Total". That works for the first three vendors you try. Then you hit one that calls it "Amount due", one that puts the total in a table, one that's a scanned photo with no text at all, and one that's a statement, not an invoice. Every vendor's layout is different, so rules turn into a pile of special cases.
A model that reads documents handles all of these in one step. We send each attachment to Claude as a PDF or image and ask two things: is this an invoice or a receipt, and if so, what are its details? Claude reads the page the way a person would, including scans and photos of receipts.
The answer has to be reliable enough to put in a spreadsheet, so we don't ask for free text. We describe the fields as a Pydantic model, and the API returns JSON that matches it:
class Invoice(BaseModel):
is_invoice: bool
kind: Literal["invoice", "receipt", "credit note", "not an invoice"]
vendor: str | None
invoice_number: str | None
invoice_date: str | None # YYYY-MM-DD
due_date: str | None
currency: str | None # ISO 4217, like USD
subtotal: float | None
tax: float | None
total: float | None
bill_to: str | None
description: str | NoneAdd a field, such as a PO number or a VAT number, and it becomes a column in the CSV.
1. Get the attachments out of your email
Both providers can hand over an email exactly as it arrived (raw MIME, what a .eml file holds). From there, Python's standard email package does the rest, so the invoice code doesn't care which provider the mail came from.
Search for emails with PDF or image attachments, using the same syntax as Gmail's search box. Then download each one with format=raw:
query = (f"has:attachment newer_than:{days}d -in:sent -in:drafts "
"{filename:pdf filename:png filename:jpg filename:jpeg}")
ids = client.search(query, 2000)
def raw(message_id):
data = client.get(f"/messages/{message_id}", params={"format": "raw"})
return base64.urlsafe_b64decode(data["raw"] + "=" * (-len(data["raw"]) % 4))Filter for emails with attachments in the date range, skipping Sent Items, Drafts, Deleted Items and Junk. Then download each one's MIME:
messages = client.messages(
"/me/messages",
f"receivedDateTime ge {since(days)} and hasAttachments eq true", # sort field first, or Graph refuses
2000,
)
skip = client.folder_ids(("sentitems", "drafts", "deleteditems", "junkemail"))
messages = [m for m in messages if m.folder_id not in skip]
def raw(message_id):
return client.get(f"/me/messages/{message_id}/$value")Then keep only what's worth reading:
READABLE = {"application/pdf", "image/png", "image/jpeg", "image/gif", "image/webp"}
for part in BytesParser(policy=policy.default).parsebytes(raw_email).iter_attachments():
content_type = part.get_content_type()
if content_type == "application/octet-stream": # many mail systems label PDFs this way
content_type = mimetypes.guess_type(part.get_filename() or "")[0]
data = part.get_payload(decode=True)
if content_type not in READABLE:
continue # Word files, zips, calendar invites
if content_type.startswith("image/") and len(data) < 15_000:
continue # logos and signature icons
yield part.get_filename(), content_type, dataThe same invoice often turns up twice, in the original email and again in a reminder. Hash each file and read it once.
2. Ask Claude what each attachment is
Each attachment is one request. Claude Haiku is fast and cheap enough for this, at about a cent for a one-page PDF, and low effort is plenty for reading a document:
response = client.messages.parse(
model="claude-haiku-5-5",
max_tokens=2048,
output_config={"effort": "low"},
system=SYSTEM,
messages=[{"role": "user", "content": [
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf",
"data": base64.standard_b64encode(data).decode()}},
{"type": "text", "text": f"File name: {name}\nEmail subject: {subject}"},
]}],
output_format=Invoice,
)
invoice = response.parsed_outputImages use "type": "image" instead of "document". The system prompt does most of the work:
- Define an invoice. It's a document from a seller that asks for, or records, a payment. Statements, quotes, purchase orders and marketing aren't invoices. Without this, every PDF with a dollar sign counts.
- Never guess. Use null for anything the document doesn't show, so a missing due date stays empty instead of being made up.
- Fix the formats. Dates are
YYYY-MM-DD, amounts are plain numbers, currency is an ISO code, and the vendor is who's being paid, not who's paying. That's what makes the CSV sortable and summable. - Treat the document as data. An attachment is something a stranger sent you, so the prompt says to ignore any instructions written in it. The fixed output format means the most a hostile PDF can do is fill in a wrong field.
Run a few requests at once with a thread pool. The Anthropic SDK retries rate limits by itself.
3. Write the CSV and the zip
Keep the invoices, sort them newest first, and write both files:
writer = csv.DictWriter(text, fieldnames=COLUMNS)
writer.writeheader()
writer.writerows(rows)
csv_path.write_text(text.getvalue(), encoding="utf-8-sig") # the BOM makes Excel show accents correctly
with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
zf.writestr("invoices.csv", text.getvalue().encode("utf-8-sig"))
for name, data in invoice_files:
zf.writestr(name, data) # "2026-11-03 Acme Ltd INV-1042.pdf"
return [File(csv_path, name="invoices.csv"), File(zip_path, name="invoices.zip")]Each file in the zip is named from what Claude read: date, vendor and invoice number, with characters that can't go in a file name removed. Your accountant can sort the folder by name and it's in date order.
Wrap it in a function with a few inputs, and Callables turns it into a form:
@gmail.deploy(title="Find invoices", timeout=900, secrets=["ANTHROPIC_API_KEY"])
def find_invoices(days: int = 30, max_attachments: int = 100, include_receipts: bool = True) -> list[File]:
"""Finds the invoices attached to your emails and returns a CSV and a zip of the files."""max_attachments caps how many attachments Claude reads in one run, which caps the cost. A run that reads 100 attachments costs about a dollar.
4. Run it on your own inbox
Get an API key at console.anthropic.com and put it in .env as ANTHROPIC_API_KEY. Then test locally with call connect, which signs you in through your browser:
git clone https://github.com/callables-app/callables-cookbook && cd callables-cookbook
pip install callables -r requirements.txt
call connect google # sign in to Google once
call gmail find_invoices --days 30git clone https://github.com/callables-app/callables-cookbook && cd callables-cookbook
pip install callables -r requirements.txt
call connect outlook # sign in to Microsoft once
call outlook find_invoices --days 30The CSV and the zip land in callables-output/. The log tells you how many attachments were read and the total per currency, a quick check against what you expected.
5. Share it with your team
Push your fork and deploy it as a Callables project. Set ANTHROPIC_API_KEY as a project secret, so nobody ever sees the key. Teammates open Find invoices, connect their own mailbox the first time, and download their own CSV and zip. Each run only reads the mailbox of the person who started it. See how scripts that run as each user work.
From there it's easy to take further:
- Run it on a schedule. Add
schedule="0 8 1 * *"and it runs on the first of every month, with the files waiting in the run history. - Ask an assistant. Connect Claude through the Callables MCP server and ask "what did we spend on software last month?". It runs Find invoices and reads the CSV for you.
- Send it on. A recipe can post each invoice to your accounting software instead of a CSV.
Good to know
- Your attachments go to Anthropic's API to be read. Under Anthropic's commercial terms, API inputs aren't used to train models. Still, think about which mailboxes you run it on.
- Check the totals before you pay anything. Claude reads documents very well, but it isn't an accountant. The CSV is a starting point that saves you the typing, not a replacement for a quick review.
- Only PDFs and images are read. Invoices sent as Word or Excel files, or as a link to a billing portal, won't show up.
- Credit notes are included as their own kind, so you can net them off against the invoices they refund.
The full, tested code, including rate limits for both mail APIs, is in the cookbook.
Turn your scripts into tools your team can run
Add @deploy to a Python function and push. Your team gets a form, schedules and run history.
Keep reading
How to bulk unsubscribe from emails with Python
Find every mailing list in your Gmail or Outlook inbox, see which ones you never read, and unsubscribe from them in bulk with the List-Unsubscribe header, then share the tool with your team.
GuidesHow to share a Python script that runs as each user
Some scripts should use a shared company key. Others should act as the person running them, on their own inbox or calendar. How to build and share the second kind without handling anyone's password or token.
GuidesHow to keep API keys out of your Python scripts
Declare the secrets a function needs, set them once in the web app, and read them from the environment. Nobody running the function ever sees them.
