Skip to main content
POST
/
v1
/
contacts
/
enrich
Enrich Contacts
curl --request POST \
  --url https://api.example.com/v1/contacts/enrich \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "name": "<string>",
  "emails": [
    "<string>"
  ],
  "names": [
    "<string>"
  ],
  "contactIds": [
    "<string>"
  ],
  "audienceId": "<string>",
  "updateContacts": true
}
'
Enrich your contacts with gender detection. This endpoint uses AI-powered name analysis to determine gender from first names or email addresses, enabling personalized greetings and segmentation.
Gender detection is 100% free with unlimited requests. Powered by the open-source gender-guesser library.

​
Request Body

​
email
string
Single email address to analyze
​
name
string
Single first name to analyze
​
emails
string[]
Array of email addresses (max 1,000)
​
names
string[]
Array of first names (max 1,000)
​
contactIds
string[]
Array of contact UUIDs to enrich
​
audienceId
string
Audience UUID - enriches all contacts without gender data
​
updateContacts
boolean
default:"false"
Update contact records in database with detected gender

​
Single Email

cURL
curl -X POST https://www.unosend.co/api/v1/contacts/enrich \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "david.smith@gmail.com"
  }'

​
Response

200 OK
{
  "data": {
    "email": "david.smith@gmail.com",
    "extractedName": "david",
    "gender": "male",
    "confidence": 100
  }
}

​
Single Name

cURL
curl -X POST https://www.unosend.co/api/v1/contacts/enrich \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria"
  }'

​
Response

200 OK
{
  "data": {
    "name": "maria",
    "gender": "female",
    "confidence": 100,
    "rawResult": "female"
  }
}

​
Batch Emails

Enrich up to 1,000 emails in a single request.
cURL
curl -X POST https://www.unosend.co/api/v1/contacts/enrich \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "john.doe@example.com",
      "maria.garcia@example.com",
      "alex@example.com"
    ]
  }'

​
Response

200 OK
{
  "data": [
    {
      "email": "john.doe@example.com",
      "extractedName": "john",
      "gender": "male",
      "confidence": 100
    },
    {
      "email": "maria.garcia@example.com",
      "extractedName": "maria",
      "gender": "female",
      "confidence": 100
    },
    {
      "email": "alex@example.com",
      "extractedName": "alex",
      "gender": "unknown",
      "confidence": 50
    }
  ],
  "stats": {
    "total": 3,
    "male": 1,
    "female": 1,
    "unknown": 1
  }
}

​
Enrich by Audience

Enrich all contacts in an audience that don’t have gender data.
cURL
curl -X POST https://www.unosend.co/api/v1/contacts/enrich \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "audienceId": "550e8400-e29b-41d4-a716-446655440000"
  }'

​
Response

200 OK
{
  "data": {
    "audienceId": "550e8400-e29b-41d4-a716-446655440000",
    "totalContacts": 1500,
    "enriched": 1500,
    "male": 720,
    "female": 680,
    "unknown": 100
  }
}

​
Enrich on Import

When importing contacts via CSV, add enrich_gender=true to automatically detect gender.
cURL
curl -X POST https://www.unosend.co/api/v1/contacts/import \
  -H "Authorization: Bearer un_your_api_key" \
  -F "file=@contacts.csv" \
  -F "audience_id=550e8400-e29b-41d4-a716-446655440000" \
  -F "enrich_gender=true"

​
Response

200 OK
{
  "data": {
    "imported": 1000,
    "duplicates": 50,
    "errors": 5,
    "total": 1055,
    "genderEnrichment": {
      "male": 480,
      "female": 420,
      "unknown": 100
    }
  }
}

​
Gender Values

ValueDescriptionConfidence
maleTypically male name75-100%
femaleTypically female name75-100%
unknownAmbiguous or unrecognized0-50%

​
Confidence Scores

  • 100% - High confidence match (e.g., “David”, “Maria”)
  • 75% - Likely match (e.g., “mostly_male”, “mostly_female”)
  • 50% - Androgynous name (e.g., “Alex”, “Jordan”)
  • 0% - Unknown or unrecognized name

​
Use Cases

Personalized Greetings

Use gender to create personalized salutations like “Dear Mr. Smith” or “Hi Maria”

Segmentation

Filter contacts by gender for targeted campaigns

A/B Testing

Test different messaging approaches by gender

Analytics

Understand your audience demographics

​
Error Responses

400 Bad Request
{
  "error": "Invalid request. Provide email, name, emails, names, contactIds, or audienceId"
}
401 Unauthorized
{
  "error": "Unauthorized"
}