API de gênero por e-mail – Solicitação individual

Visão geral da solicitação

Do endereço de e-mail à estimativa

A GenderAPI analisa a parte local do endereço, extrai o primeiro nome mais provável e usa esse nome na estimativa de gênero. Informe o contexto de país quando souber a região do usuário.

01Entrada de e-mailmichael.smith@example.com

02Extração do nomeMichael

03Estimativamale · 97%

MétodoPOST

Tipo de conteúdoapplication/json

AutenticaçãoBearer token

Custo em créditos1 consulta

HDR

Cabeçalhos HTTP obrigatórios

Autorize a solicitação

Content-Typeapplication/json

AuthorizationBearer YOUR_API_KEY

Corpo JSON da solicitação

Parâmetros

Parâmetro	Tipo	Obrigatoriedade	Descrição
`email`	string	Obrigatório	Endereço de e-mail a analisar. A GenderAPI extrai o primeiro nome mais provável antes da estimativa.
`country`	string	Opcional	Código de país ISO 3166-1 alfa-2, como BR ou US, para adicionar contexto regional.
`askToAI`	boolean	Opcional	Quando true, usa a IA como alternativa se o nome extraído não tiver resultado no banco de dados.

Suporte de IA

askToAI é avaliado após a extração do nome e somente quando o nome extraído não é encontrado no banco de dados. O endpoint de e-mail não aceita forceToGenderize.

Exemplos de código

Envie uma solicitação por e-mail

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())

Resposta 200

Nome extraído e estimativa

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"
}

Campos da resposta

Campo	Tipo	Descrição
`status`	boolean	Indica se a solicitação foi concluída com sucesso.
`used_credits`	integer	Créditos consumidos por esta solicitação.
`remaining_credits`	integer	Créditos disponíveis após a solicitação.
`expires`	integer	Data de expiração do pacote em formato de timestamp UNIX.
`q`	string	E-mail original enviado na solicitação.
`name`	string	Primeiro nome extraído do endereço de e-mail.
`gender`	string \| null	Valor estimado: male, female ou null.
`country`	string	Código de país considerado na estimativa.
`total_names`	integer	Quantidade de amostras que sustentam a estimativa.
`probability`	integer	Probabilidade da estimativa em porcentagem.
`duration`	string	Tempo de processamento no servidor.

Use um endereço de e-mail completo e válido

A extração do nome depende da estrutura do endereço. Caixas de entrada genéricas, aliases ou partes locais sem nomes reconhecíveis podem não gerar resultado; verifique name, gender eprobability antes de usar a estimativa.

Próximo guia

Analise vários endereços de e-mail

Solicitação de vários e-mailsProcesse vários endereços em uma solicitação →Solicitação individual por nomeEnvie diretamente um primeiro nome conhecido →