Skip to main content

Security and compliance

Mailwoman runs inside your infrastructure. The addresses you process stay there, because no step in 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. or a geocode sends them anywhere else. This page describes that behavior precisely enough for you to check it, and links the artifacts a security review asks for.

What the library sends over the network​

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. or a geocode sends no request over the network. Those calls read model weightsmodel weightsThe learned parameters of the neural classifier, shipped as ONNX files in the @mailwoman/neural-weights-* packages. Weights are locale-specific bundles that include the model, tokenizer, and a model-card.json metadata file. and 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. files from local disk and return. No published package contains telemetry, analytics, crash reporting, a version check or a usage ping. Mailwoman's install runs no lifecycle scripts: npm install fetches tarballs and stops.

The network behavior has four boundaries:

  • RemoteResolver is opt-in, and you own the endpoint. It separates parser nodes 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. service inside your own network. It throws unless you construct it with an endpoint URL. It is never a default, and we do not operate the service.
  • The dataset build commands download datasets. mailwoman gazetteer build and related commands fetch from the US Census, Geofabrik, adresse.data.gouv.fr and the FCC. You run these commands deliberately, at build time, separately from 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 data pull command downloads reference data. mailwoman data pull fetches prebuilt 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., POIpoint of interest (POI). A named place that is not strictly an address — landmark, transit stop, venue, amenity, or franchise. Mailwoman tags these as venue and resolves them through the gazetteer. and localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. bundlesevidence bundleThe pair of retrieval-augmented input channels (street-type + locality-surface) that feed lexicon membership as soft per-token evidence alongside the text. Shipped in 6.7.0; trained natively from step 0 in the from-scratch base line. from public.mailwoman.ai. A HEAD request checks the remote size, and then a GET streams the file to disk. The command runs only when you invoke it. Your first ten minutes shows the exchange line by line.
  • The browser runtime downloads its 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.'. @mailwoman/neural/web/loader fetches 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.' and data artifacts once, from a URL your application supplies. The query text stays in the page. Our hosted Earth demo is a deployment of that runtime. It serves those artifacts from public.mailwoman.ai and calls tiles.mailwoman.ai for coarse map centering. The demo makes both of those requests. The library you install makes neither.

How it is licensed​

One codebase is available under two licenses:

  • AGPL-3.0-only. The full text and the dual-license header are in LICENSE.md. The license has one condition. If you distribute software built on Mailwoman, or run it as a network service that others use, those users are entitled to your corresponding source under the same license.
  • A commercial license. It releases you from that condition. The reference terms are in COMMERCIAL-LICENSE.md. That document is a template and grants no rights. Only the executed agreement is binding. Rates are on Pricing.

The code license and the data license are separate. Our license covers the code. Data provenance, below, describes the terms under which the reference data is licensed.

Software bill of materials​

We publish an SBOM for the mailwoman package in two open standards: SPDX 2.3 and CycloneDX 1.5. The built-in npm sbom command generates both, without third-party tooling in the trust path. It runs against the published tarball instead of the working tree, so the SBOMs describe what a consumer installs and exclude development-only dependencies.

The files are served under /sbom/ and committed to the repository. Generation is a release-time step that runs on demand instead of in CI, so the newest published SBOM can lag behind the newest release. Check the version in the filename before you scan it.

npm Trusted Publishing uses GitHub OIDC and removes the need for a long-lived registry tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. that could leak. Packages do not currently include a sigstore provenance attestation.

Data provenance​

The pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-hint → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. records each source with its license at the point the source enters. The legal notices ship as THIRD_PARTY_NOTICES.md in the source distribution. Each built data artifact includes its own ATTRIBUTION.json. That file records the source, release and license it was built from. The catalog of sources and their terms is data licensing and provenance.

Two items on that page matter to a review, and we would rather you heard them from us:

  • The OpenStreetMapOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. tier reaches no published artifact. The rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. extractsextractA partial output file of the corpus build, written in Parquet format. The training pipeline streams extracts row by row. in @mailwoman/osm are built and deliberately unpublished, on npm and in the demo alike, because OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. data is share-alike and enabling that tier is waiting on legal review. The served candidate 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. does contain a Northern Ireland 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. fold derived from OpenStreetMapOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. under ODbL: 4,757 places, measured 2026-09-27 by downloading gazetteer/2026-08-25b/candidate.db in full and counting the rows in that fold's id range. What ODbL asks of that is with counsel, and this page states no conclusion about it. The data products page shows what each published bundleevidence bundleThe pair of retrieval-augmented input channels (street-type + locality-surface) that feed lexicon membership as soft per-token evidence alongside the text. Shipped in 6.7.0; trained natively from step 0 in the from-scratch base line.'s own manifest records.
  • One source's license is recorded inconsistently in our own files. Who's On FirstWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. appears as CC0 in the provenance catalog and as CC-BY 4.0 in the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. package's own notes. Until that is settled, attribute Who's On FirstWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations..

Report a vulnerability​

Report vulnerabilities privately by email instead of in a public issue. The policy, the scope and what to include are in SECURITY.md.