Blog
Guides

How to automatically extract invoices from Gmail and Outlook into a spreadsheet

DK
Dan Kowalsky
Founder ยท

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.

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 | None

Add 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))

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, data

The 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_output

Images 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 30

The 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.

See how it works

Keep reading