Allan Simões AdegasPortuguês
Menu
Back to home

Mail-Extractor

In development

Information extraction from corporate email, with every value traceable to the exact snippet of the message.

Role
Author · Asigas product
Started
2026
from: compras@cliente.com.br#4821R$ 1.240,0028/11/2026pedido-4821.pdforder#4821amountR$ 1.240,00due date28/11/2026Pub/Sub · customer queue
Project illustration
2
providers: Gmail and Outlook (OAuth)
5
attachment types read (PDF, DOCX, TXT, CSV, XLSX)
60+
test files

Overview

Companies receive orders, confirmations and invoices by email and someone copies the data into another system. Mail-Extractor routes messages by rule and extracts fields with source evidence. The personal Gmail connector was exercised against the provider. Outlook and corporate Gmail workflows were tested with simulated responses.

It's the productized evolution of what I learned at BTG: reliable extraction needs evidence, and every delivered value points to the snippet of the email it came from.

What it does

Rule-based routing
Configurable rules decide which project each email belongs to, with a simulator to test before switching them on.
Regex or AI extraction
Variables extracted by regular expression or by a language model (Claude or Gemini), including attachment text.
Evidence for every value
The normalized email body is the anchor: every value keeps the position of the snippet it came from.
Multi-tenant
Per-customer roles (admin, editor, viewer), a team screen and platform administration.

Architecture

Architecture: Mail-ExtractorGmail · Outlook → fetch. fetch → route. route → extract. extract → deliver. deliver → Customer queue. route → PostgreSQL. extract → Email bodiesGmail · OutlookOAuthfetchMIME and attachmentsrouterulesextractregex or AIdelivercontract v1Customer queuePub/SubPostgreSQLrules, results, evidenceEmail bodiesCloud Storage or disk
A pipeline of independent stages, each with its own worker.

Decisions and trade-offs

Two ways to run
On Google Cloud it uses Pub/Sub and Cloud Storage; on a single VPS the same stages use Redis and a directory. The domain doesn't change.
Layered architecture
A pure domain, use cases and adapters (mail providers, AI, queues) separated by ports, which allows testing against local emulators.

Quality and operations

  • Tested against local Pub/Sub and Cloud Storage emulators; integration tests skip when Docker is unavailable.
  • Lint, type checks and tests in one command (make check).
  • Single-VPS deployment with Docker Compose and Caddy already prepared.

Status and next steps

  • In development: the full flow works locally with demo data; the first production customer is next.

Stack

PythonFastAPIPostgreSQLRedisGoogle Pub/SubCloud StorageClaude / GeminiReactTanStack