email-receipt-scanning

name	email-receipt-scanning
description	Domain knowledge for scanning Gmail for receipt and invoice emails. Reference this when processing email-based receipts.

Email Receipt Scanning

Purpose

Provides Gmail search queries, Danish sender patterns, email content type detection, and deduplication rules for scanning a user's inbox for receipts and invoices. Used by the /smartspender:receipt email command.

Prerequisites

This skill requires the Gmail MCP server to be configured in the user's environment. The following MCP tools are needed:

• gmail_search or equivalent — search emails by query
• gmail_get_message or equivalent — read email content and metadata
• gmail_get_attachment or equivalent — download PDF attachments

If Gmail MCP is not available, commands using this skill should fail gracefully with a clear message.

Gmail Search Queries

Primary Search Query

Search for receipt and invoice emails using this combined query:

subject:(faktura OR kvittering OR receipt OR invoice OR ordre OR order OR betaling) has:attachment after:{YYYY/MM/DD}

Where {YYYY/MM/DD} is either:

• The last_email_scan timestamp from settings.csv (incremental scan)
• A calculated date based on the days argument (e.g., 30 days back)
• Default: 90 days back if no previous scan and no argument

Supplementary Queries

If the primary query returns few results, also try:

from:(*faktura* OR *invoice* OR *noreply* OR *no-reply*) has:attachment after:{YYYY/MM/DD}

subject:(ordrebekraeftelse OR orderbekraeftelse OR betalingsbekraeftelse) after:{YYYY/MM/DD}

Query Notes

• has:attachment ensures only emails with files are returned (most invoices are PDF attachments)
• Danish keywords (faktura, kvittering, betaling) catch Danish vendor emails
• English keywords (receipt, invoice, order) catch international vendors
• Date filter prevents re-scanning old emails

Danish Sender Patterns

Map known email sender domains to vendor IDs for faster vendor detection:

Sender Pattern	Vendor ID	Vendor Name	Type
*@tdc.dk	tdc	TDC	Telecom
*@tdcnet.dk	tdc	TDC	Telecom
*@telenor.dk	telenor	Telenor	Telecom
*@telia.dk	telia	Telia	Telecom
*@orsted.dk	orsted	Oersted	Electricity
*@hofor.dk	hofor	HOFOR	Water
*@norlys.dk	norlys	Norlys	Electricity
*@ewii.dk	ewii	EWII	Utility
*@dinenergi.dk	dinenergi	Din Energi	Electricity
*@netflix.com	netflix	Netflix	Streaming
*@spotify.com	spotify	Spotify	Streaming
*@amazon.com	amazon	Amazon	Online order
*@amazon.de	amazon	Amazon	Online order
*@zalando.dk	zalando	Zalando	Online order
*@ikea.com	ikea	IKEA	Online order
*@wolt.com	wolt	Wolt

For senders not in this table: extract the domain name as a starting point for vendor detection, then fall through to the invoice-parsing skill's vendor detection workflow.

Email Content Types

Receipt emails come in three forms. Detect and handle each:

Content Type	Detection	Extraction Method
PDF attachment	Email has .pdf attachment	Download attachment → process as PDF invoice
Inline HTML	Email body contains structured receipt data, no PDF	Extract from email HTML body
Both	PDF attachment + summary in body	Prefer PDF attachment (more complete)

PDF Attachment Priority

When an email has both a PDF attachment and inline content, always process the PDF. The inline content is typically a summary or notification, while the PDF is the full invoice.

Inline HTML Extraction

For emails without PDF attachments (e.g., Wolt order confirmations, Nemlig receipts):

1. Parse the email HTML body
2. Look for structured tables with item names, quantities, prices
3. Extract total from summary section
4. Set file_reference to email:{message_id} (no file to archive)

Deduplication

Timestamp-Based Scan Window

• Read last_email_scan from settings.csv
• Only search emails received after this timestamp
• After successful scan, update last_email_scan to current datetime

Cross-Check with receipts.csv

Before processing each email:

1. Detect vendor and date from email metadata
2. Extract total (from subject line or quick body scan)
3. Check receipts.csv for existing receipt with same date + merchant + total_amount
4. If match found: skip and note in scan summary as "allerede registreret"

Deduplication Fields

Field	Source	Match Rule
date	Email date or invoice date	Same day
merchant	Sender domain mapping or vendor detection	Same normalized merchant
total_amount	PDF extraction or email body	Exact match

Date Range Calculation

Scenario	Date Range
last_email_scan exists in settings.csv	From last_email_scan to now
User provides days argument	From (today - days) to now
Neither (first scan)	From (today - 90 days) to now

If the user provides a days argument, it overrides last_email_scan. This allows rescanning a specific period.

Email Filtering Heuristics

Not every email matching the search query is a receipt. Apply these filters:

Include

• Emails with PDF attachments from known vendor domains
• Emails with "faktura" or "kvittering" in subject
• Order confirmation emails with itemized totals

Exclude

• Marketing emails (subject contains "tilbud", "kampagne", "nyhedsbrev" without "faktura"/"kvittering")
• Password reset or account notification emails
• Shipping notifications without invoice content
• Emails already processed (deduplication check)

Examples

Example 1: Incremental Scan

Context: last_email_scan = 2026-01-15 in settings.csv

Search query: subject:(faktura OR kvittering OR receipt OR invoice OR ordre OR order OR betaling) has:attachment after:2026/01/15

Results: 4 emails found

1. TDC faktura (2026-01-20) — PDF attachment — known vendor
2. Oersted aarsopgoerelse (2026-01-25) — PDF attachment — known vendor
3. Wolt ordrebekraeftelse (2026-01-28) — inline HTML — no parser
4. Spam email about "tilbud" — filtered out

After processing: Update last_email_scan to 2026-02-01

Example 2: First-Time Scan with Days Argument

Context: No last_email_scan in settings.csv. User runs /smartspender:receipt email 30

Search query: subject:(faktura OR kvittering OR receipt OR invoice OR ordre OR order OR betaling) has:attachment after:2026/01/02

Results: Emails from the last 30 days

Related Skills

• See skills/document-parsing/SKILL.md for vendor detection, parser lookup workflow, and general extraction rules
• See skills/data-schemas/SKILL.md for the CSV file structure (email receipts use source: email)