What Mailwoman is

The question

You have addresses. They came from a signup form, a CRM export, a spreadsheet a field crew filled in on a phone. You need them split into fields, and you need coordinates. Every tool that does this seemsexpectation-maximizationAn iterative algorithm that estimates model parameters when some variables are unobserved. In Mailwoman's matcher, EM learns the Fellegi-Sunter m and u parameters from unlabeled data — no training labels needed. to want an account before it will answer. So what is Mailwoman, and where does it run?

The analog

A sorting clerk reading an envelope does two jobs, in that order. First they read it: this group of characters is the house numberhouse numberThe numeric or alphanumeric identifier of a building on a street. Mailwoman's house_number component; its position relative to the street name flips between locales., that one is the town, the one at the end is the postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.. Then they look it up — they take the town they read and work out where it is.

Mailwoman keeps those two jobs apart. npm install mailwoman gives you the reading job: a function that takes apt 4b 350 5th ave new york ny 10118 and returns a tree of tagged components, each with a confidence score. The looking-up job is a second pass that walks that tree and attaches coordinates from a gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. — a database of places and where they are.

The reading pass runs a sequence labeler: a small modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' that assigns one tag to each piece of the input, the way a spam filter assigns one labelcomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. to a message. That is the whole of the modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' vocabularyvocabularyThe fixed set of tokens a tokenizer can produce. Mailwoman's SentencePiece vocabulary is tens of thousands of subword pieces, with byte fallback for anything outside it. this page needs.

Where it runs

Inside your process. The English modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' is a 39.4 MB file that arrives as an npm package, @mailwoman/neural-weights-en-us, and loading it is a file read. Node 24.18.0 or later. A browser build runs the same stagesstageOne of the dataflow stages in the runtime pipeline (normalize, locale gate, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone). through @mailwoman/neural/web-loader.

Three consequences follow from that, and they are the reason the design is shaped this way:

• Nothing to be down. Parsingaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. has no upstream. If your process is running, the parser is running, and a network outage between you and us cannot affect a parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates., because there is no network between you and us.
• No meter. You are not billed per address. Re-parsingaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. the same string a thousand times because a user kept editing a form field costs you a thousand function calls and nothing else.
• The addresses stay where they are. A parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. call opens no network socket. Customer addresses never reach our infrastructure, which is a conversation you then do not have to have with your compliance team. The detail, including the one opt-in code path that does make a request, is on Security and compliance.

What it is not

It is not a hosted service you sign up for. There is no API key, no dashboard, no quota. If you want an HTTP endpoint, you run one: @mailwoman/api and the Nominatim-, Photon- and libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it.-compatible drop-ins are servers you deploy on your own hardware, pointed at your own data.

It is not a substitute for a postal authority's address file. Royal Mail's PAF, Ordnance Survey's AddressBase and the USPS address products answer a question Mailwoman does not: does this delivery point exist, and will mail arrive there? Those are licensed authoritative registersinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise. of real letterboxes. Mailwoman reads the string you hand it and matches what it can against open data. It will tell you that a string looks like 350 5th Ave, New York, NY 10118 and where that is. It will not tell you that somebody lives there.

What it costs

You carry the data. The modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' file sits on your disk, and geocodinggeocodingThe process of converting an address into geographic coordinates (latitude and longitude). Mailwoman geocodes in a multi-tier cascade: exact address-point match → street interpolation → locality centroid. Each tier is progressively coarser but more widely available. wants a gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. database that you download once and keep. That is the trade for having no server: the bytes are your problem rather than ours.

CoveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. is whatever open data covers, and it is uneven by countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head.. What ships today gives the per-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. picture, including the localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. where the claim is thin.

And the two jobs arrive separately. Parsingaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. works the moment npm install finishes. GeocodinggeocodingThe process of converting an address into geographic coordinates (latitude and longitude). Mailwoman geocodes in a multi-tier cascade: exact address-point match → street interpolation → locality centroid. Each tier is progressively coarser but more widely available. does not, until the gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. is on disk.

Related

• Install and first parse — the reading job, in about ten lines.
• Your first ten minutes — the looking-up job, once the gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. is on disk.
• What ships today — versions, footprints, localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for., and the gaps.