MailBudget is a proactive, modular finance assistant that leverages Postmark's robust inbound email parsing capabilities to automate financial insights and inbox cleanup.
At its core, MailBudget functions as a "hub-and-spoke" system—Postmark serves as the universal inbox gateway, while lightweight plug-in adapters (such as Gmail Cleanup) can be added or removed without impacting the core application.
Security (DKIM/SPF) validation happens upfront, AI-driven insights are generated downstream, and structured data is neatly stored for easy access.
With MailBudget, email receipts become actionable data, spending spikes are proactively identified, and your inbox stays tidy—all without manual intervention
🎬 Demo
⚠️ Warning: Any data you share will appear in a public database, so please don't share any receipts with confidential information. If you do accidentally send something, please reach out to me and I'll delete it.
Forward a Receipt
Send any email receipt or invoice to the following address:
3728c7c80a75490dd061ca9611e2ba2e@inbound.postmarkapp.com
Note: Inbox cleanup requires running the app locally with your own Gmail OAuth keys. A dry-run preview mode is included so nothing is deleted by accident.
💻 Code Repository
All source code, setup instructions, and a one-click Docker deployment are on GitHub:
Every day, inboxes fill up with receipts, invoices, and bank notifications—valuable financial data trapped in unstructured text. MailBudget unlocks that data.
By leveraging Postmark as our rock-solid inbound gateway, MailBudget turns inbox clutter into clarity:
✅ Parses every receipt or invoice into clean, structured data
✅ Surfaces anomalies & trends with an AI/RAG pipeline
🧹 After processing, it can delete the original email so your workspace stays squeaky-clean
🛠 How It Works
At a glance: MailBudget is a hub-and-spoke system—Postmark acts as the universal inbox gateway, while lightweight plug-in adapters (e.g., Gmail Cleanup) bolt on or…
Postmark Inbound & Send APIs handle all email I/O and security (DKIM, SPF, spam filtering) so I could focus on features, not deliverability.
Node.js, NestJS & TypeScript power the server.
GPT-4 extracts structured data from email bodies and crafts the insight summaries.
Airtable is the single source of truth for transactions, making RAG queries trivial.
Gmail Cleanup Adapter speaks to Google via OAuth2; because the core logic lives behind Postmark webhooks.
💡 Challenges & Key Implementations
Agentic toolkit – The GPT-4 agent isn't a one-shot prompt; it wields named tools defined in src/ai-agent/services such as queryAirtable, upsertTransaction, listSubscriptions, and sendInsightEmail. Armed with the caller's context it can chain calls—e.g., fetch last-30-days spend, compare against today, then craft a spike alert—before deciding to deliver or discard.
Multi-line & mixed-format receipts – Many vendors stuff several SKUs in one email while others attach PDF invoices. We built a two-pass extractor: first an HTML/Markdown pass, then (if needed) a PDF→text pass. Parsed line-items roll up into a single transaction but stay individually searchable.
False-positive guardrail – Not every email that looks like a receipt is one. A lightweight classifier checks sender domain + template heuristics + AI confidence; uncertain messages get labeled "informational" so they don't pollute the ledger.
Idempotency & duplicates – Postmark's webhook ID plus an email hash ensure the same email can't be processed twice—even across redeploys.
Biggest win? Keeping the architecture modular: Postmark at the center, tiny adapters at the edge, and AI doing the heavy lifting in between. It meant I spent more time polishing the user experience (and adding dry-run / WCAG formatting) instead of wrangling infrastructure.
AI Agent Workflow Example
Below is a real trace of MailBudget’s AI agent workflow:
Picture a coffee-shop founder drowning in hundreds of emailed Stripe receipts every month or a visually-impaired freelancer who relies on screen-readers to track deductible costs.
MailBudget turns those noisy inboxes into quiet ledgers:
Saves hours of manual spreadsheet work for indie founders.
Spots duplicate subscription charges before they become costly leaks.
Gives accountants a single Airtable feed they can integrate with existing tooling.
In short, less grunt work, fewer surprises, more informed financial decisions.
♿ Accessibility
Emails generated by MailBudget follow WCAG AA guidelines: proper semantic headings, high-contrast colour palette, and ALT text for every table cell so screen-reader users get the same insight as everyone else.
The public demo is zero-sign-up— just forward an email—so you can try it without technical hurdles.
🚀 What's Next
Custom Domain - configure our own custom domain that is easy to remember when forwarding emails.
Outlook Cleanup Adapter – plug-in already sketched, will extend the same OAuth flow to Microsoft 365.
CSV / QuickBooks exporter – one-click hand-off to popular accounting suites.
The modular design (Postmark hub, adapters on the edge) makes each of these only a weekend project away.
Please note that API ip address has changed to: 54.164.243.239/api/docs