What Mailwoman is

The question

You have addresses from a signup form, a CRM export, or a spreadsheet that a field crew filled in on a phone. You need them split into fields, and you need coordinates. Most tools that do this require an account first. This page explains what Mailwoman is and where it runs.

The analog

A sorting clerk reading an envelope does two jobs in order. First the clerk reads it and identifies 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., the town and the postcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.. Then the clerk looks up where that town is.

Mailwoman keeps those two jobs separate. 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 lookup 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 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 a database of places and their locations.

The reading pass runs a sequence labeler. This is 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. This page needs no other 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..

Where it runs

Mailwoman runs inside your process and requires Node 24.18.0 or later. 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 distributed as the npm package @mailwoman/neural-weights-en-us, and loading it is a file read. A browser build runs the same stagesstageOne of the dataflow stages in the runtime pipeline (normalize, locale check, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone). through @mailwoman/neural/web/loader.

This design has three consequences:

• There is no service to go down. The parser has no upstream dependency. If your process is running, the parser is running. A network outage 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 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. makes no network connection to us.
• There is 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 a thousand function calls and no billed request.
• 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, so customer addresses never reach our infrastructure, and your compliance review does not need to cover that transfer. Security and compliance gives the details, including the one opt-in code path that does make a request.

What it is not

It is not a hosted service you sign up for. It has no API key, dashboard or quota. If you want an HTTP endpoint, you run one yourself. @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 against 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 that Mailwoman does not: does this delivery point exist, and will mail arrive there? Those products 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 give it and matches what it can against open data. It can tell you that a string looks like 350 5th Ave, New York, NY 10118 and where that address is. It cannot tell you that somebody lives there.

What it costs

You store 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. needs 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. Without a server, you manage those files yourself.

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. matches what open data covers, and it varies 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. details, including the localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. with weak 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..

The two jobs become available separately. The parser works as soon as npm install finishes. The geocoder works after you put 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. 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.