Support

Mailwoman is maintained in the open by a small team. Everything below routes to a real person; none of it routes to a queue.

I found a bug

File it at github.com/sister-software/mailwoman/issues. There is no form to fill in, so five things make the difference between an issue that gets fixed and one that gets a follow-up question:

• The exact input string, as typed. Copy it, do not retype it — whitespace and punctuation are the bug about half the time.
• What you expected, and what you got.
• The output of npx mailwoman doctor. It names your versions, your Node build, and which data layerslayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. you have, which is most of the reproduction.
• Whether 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. was wired. A missing coordinate on 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.-only pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. is the documented behaviour, not a bug.
• The localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for., if it is not en-US.

A wrong 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. is worth filing. Send the address that broke rather than a description of the class of address that broke: a concrete string can go straight into a test case, and a description cannot.

If an AI coding assistant is filing the issue on your behalf, run npx mailwoman skill install first — it teaches the assistant this diagnostic flow directly, so the report arrives with the right evidence already attached.

I found a security issue

Do not open a public issue. Email teffen@sister.software with the impact, the reproduction, and the version you found it on. The full policy, including what is in and out of scope, is in SECURITY.md.

I want to show you rather than describe it

The demo runs the same parser and the same 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. in your browser tab, against the published 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.'. It reads the address out of the URL, so /demo?q=350+5th+Ave,+New+York loads with your input already in the box. Put that link in the issue and we see exactly what you saw, with no install on either side.

If your input is something you cannot paste into a public page, say so in the issue and we will find another way to look at it.