Gender from an email address or a username: the extraction is the hard part

There are two jobs hiding inside "get a gender from this email address", and they fail in completely different ways.

1. Extraction — turn ayse.yilmaz84@example.com into ayse
2. Classification — turn ayse into female

Classification is the part with the benchmarks and the marketing pages. Extraction is the part that actually breaks, and because it breaks before the lookup, none of the confidence machinery downstream can see it happening.

This post is about the first job, including the inputs where we get it wrong.

What we actually do to an email address

No cleverness, four steps, and it is worth knowing exactly:

1. Take everything before the @ and lowercase it.
2. Replace every run of . _ - + and digits with a space.
3. Split on whitespace, discard titles (dr, mr, mrs…) and single-letter tokens, which are initials.
4. Return the first surviving token.

So ayse.yilmaz84@example.com becomes ayse yilmaz, then ayse. jean.dupont+news@x.fr becomes jean. dr.hans.mueller@x.de drops the title and returns hans.

Usernames get one extra step in front: camelCase and PascalCase are split first, so AyseYilmaz becomes Ayse Yilmaz before the separators and digits are stripped. A leading @ is trimmed. xX_kevin_Xx comes out as kevin.

The endpoints mirror the shape of /api:

curl "https://namegender.com/api/email?email=ayse.yilmaz84@example.com" \
  -H "Authorization: Bearer YOUR_KEY"

curl "https://namegender.com/api/username?username=AyseYilmaz" \
  -H "Authorization: Bearer YOUR_KEY"

Both return the same response body as a plain name lookup, with q echoing your raw input and name reporting what was extracted from it.

Where it goes wrong

Here is the honest table. Every row is real output from the live engine, with no country hint:

The first seven rows behave. The last four are the ones to plan around, and they split into two distinct problems.

Rows 8–10: real names in the long tail. Admin, User and The are all attested as given names somewhere in a 195-country reference dataset. They come back with total_names: 0 and confidence: unverified, which is the system correctly reporting that it has no counted evidence — but it still names a gender.

Row 11 is the nastier one. j.smith@example.com drops the initial j, leaving smith, and Smith is a genuine given name with 552 recorded observations. The answer arrives with confidence: high because the classification is fine. The extraction is what failed — a surname was promoted to a given name, and nothing in the response can tell you that.

This is the general rule for this category, and it is why we keep saying it: a confidently wrong answer is worse than a null, because nothing downstream can detect it.

The pre-filter to run before you spend credits

Four rules. The first three cost nothing and remove most of the damage.

1. Drop role addresses before you send them. Match the local part against a blocklist and skip the lookup entirely:

admin, info, sales, support, contact, hello, help, office, billing,
accounts, noreply, no-reply, donotreply, postmaster, webmaster,
marketing, press, jobs, careers, hr, legal, privacy, security, team

These are not people. Filtering them locally is faster than an API round trip and cheaper than a credit.

2. Require at least two extractable tokens, or a token you can vouch for. mgarcia@x.es and j.smith@x.com are both a compressed initial plus a surname. The first fails safely; the second does not. If the local part has no separator, or has exactly one token after stripping initials, treat the result as low-trust regardless of what confidence says.

3. Prefer a real name column. If your database has a first_name field, use it. Email extraction is a fallback for the rows where you have nothing else, not a substitute for data you already hold.

4. Read name, not just gender. The name field reports what was actually looked up. If you expected Ayse and you got Smith or The, the classification is irrelevant — you have an extraction bug, and it will be systematic across your whole file rather than random.

That fourth habit is the one that generalises. It separates two failure modes that otherwise blur together, and it is the same discipline that catches the surname-first name-order problem in Chinese input.

On thresholds

For email and username input specifically, we would set the bar higher than for a clean name column:

The reason for the extra strictness is not that classification is worse here. It is that extraction adds a failure mode the confidence fields cannot see, so you need the margin somewhere else.

The field-by-field meaning of probability, total_names and confidence is in reading a gender response properly. If your input is a file rather than an API call, the same fields land as columns — see adding a gender column to a spreadsheet.

Email addresses are personal data in most jurisdictions you are likely to be operating in. What we do with the ones you send is in the data processing agreement, and it is short.

Everything in the table above is reproducible on a free key — 100 credits a day, no card. If your list produces a failure we have not listed here, that is the more interesting result, and we would rather hear about it.