Gender From Email API – Single Request Documentation

Request overview

From email address to prediction

GenderAPI analyzes the local part of the address, extracts the most likely first name and uses that name for gender prediction. Supply country context when you know the user’s region.

01Email inputmichael.smith@example.com

02Name extractionMichael

03Predictionmale · 97%

MethodPOST

Content typeapplication/json

AuthenticationBearer token

Credit cost1 lookup

HDR

Required HTTP headers

Authorize the request

Content-Typeapplication/json

AuthorizationBearer YOUR_API_KEY

JSON request body

Parameters

Parameter	Type	Requirement	Description
`email`	string	Required	Email address to analyze. GenderAPI extracts the most likely first name before prediction.
`country`	string	Optional	ISO 3166-1 alpha-2 country code, such as US or TR, to add regional context.
`askToAI`	boolean	Optional	When true, use the AI fallback if the extracted name has no database result.

AI fallback

askToAI is evaluated after name extraction and only when that extracted name is not found in the database. The email endpoint does not accept forceToGenderize.

Code examples

Send an email request

cURL

curl -X POST "https://api.genderapi.io/api/email" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"email":"michael.smith@example.com","country":"US","askToAI":true}'

JavaScript

const response = await fetch("https://api.genderapi.io/api/email", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer YOUR_API_KEY" },
  body: JSON.stringify({ email: "michael.smith@example.com", country: "US", askToAI: true })
});
const data = await response.json();

Python

import requests

response = requests.post(
  "https://api.genderapi.io/api/email",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={"email": "michael.smith@example.com", "country": "US", "askToAI": True}
)
print(response.json())

200 response

Extracted name and prediction

JSON

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "michael.smith@example.com",
  "name": "Michael",
  "gender": "male",
  "country": "US",
  "total_names": 10345,
  "probability": 97,
  "duration": "5ms"
}

Response fields

Field	Type	Description
`status`	boolean	Whether the request completed successfully.
`used_credits`	integer	Credits consumed by this request.
`remaining_credits`	integer	Credits available after the request.
`expires`	integer	Package expiration time as a UNIX timestamp.
`q`	string	Original email submitted in the request.
`name`	string	First name extracted from the email address.
`gender`	string \| null	Predicted value: male, female or null.
`country`	string	Country code considered for the prediction.
`total_names`	integer	Number of samples supporting the prediction.
`probability`	integer	Prediction confidence as a percentage.
`duration`	string	Server processing time.

Use a valid, complete email address

Name extraction depends on the address structure. Generic inboxes, aliases or local parts without recognizable names may produce no result; check name, gender and probability before using a prediction.

Next guide

Analyze multiple email addresses

Email multiple requestProcess several addresses in one request →Name single requestSend a known first name directly →