> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encrata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Email Gender

> Predict the likely gender and country behind an email address. 1 credit, with free repeats for 6 months.

## Overview

Email Gender infers the **likely gender** and **country** of the person behind an
address from the name embedded in the local part (for example `jane.doe@` or
`j.smith@`). It returns a single verdict with a confidence score, backed by
genderapi.io. Use it to personalise outreach, segment a list, or fill a missing
`gender` field before a campaign.

Predict for a single address here (1 credit), or label a whole list with the
[bulk job pipeline](#bulk-asynchronous) below.

## Authentication

Requires an API key in the `Authorization` header.

```bash theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```

## Request

<ParamField body="email" type="string" required>
  The email address to predict gender for.
</ParamField>

### Example request

<CodeGroup>
  ```bash cURL (API Key) theme={"dark"}
  curl -X POST "https://developer.encrata.com/api/email/gender" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"email": "jane.doe@example.com"}'
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.post(
      "https://developer.encrata.com/api/email/gender",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={"email": "jane.doe@example.com"},
  )
  print(resp.json())
  ```

  ```javascript JavaScript theme={"dark"}
  const resp = await fetch("https://developer.encrata.com/api/email/gender", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email: "jane.doe@example.com" }),
  });
  const data = await resp.json();
  ```
</CodeGroup>

## Response

<ResponseField name="email" type="string">
  The email address that was analysed.
</ResponseField>

<ResponseField name="gender" type="string">
  The predicted gender: `male`, `female`, or `unknown` when the name cannot be
  resolved with confidence.
</ResponseField>

<ResponseField name="country" type="string | null">
  The most likely country for the name as an ISO alpha-2 code (for example `US`,
  `GB`), or `null` when no country signal is available.
</ResponseField>

<ResponseField name="probability" type="number">
  Confidence in the `gender` verdict, from `0` to `100`. A low value on an
  `unknown` verdict means the name was ambiguous or not recognised.
</ResponseField>

<ResponseField name="credits" type="number">
  Credits charged for this request. `1` on a fresh charge, or `0` when you were
  already charged for this address within the billing window (a free repeat).
</ResponseField>

<ResponseField name="cached" type="boolean">
  Present and `true` only when the verdict was served from cache. This is
  independent of billing: a cached result is still charged `1` on your first
  request for that address in the window.
</ResponseField>

## Errors

Errors return a JSON body of the form `{"error": "<message>"}` with the matching
HTTP status code.

| Status | Message                                             | Cause                                    |
| ------ | --------------------------------------------------- | ---------------------------------------- |
| `400`  | `Invalid request body`                              | Malformed JSON                           |
| `400`  | `Invalid email address`                             | Address fails syntax parsing             |
| `401`  | `API key required` / `bad key`                      | Missing or invalid API key               |
| `401`  | `Unauthorized`                                      | The key's account could not be resolved  |
| `402`  | `Insufficient credits. Please top up your account.` | Not enough credits and not a free repeat |
| `405`  | `Only POST method is allowed`                       | Wrong HTTP method                        |
| `502`  | `Gender lookup failed. Please try again.`           | Transient provider error, retry shortly  |
| `503`  | `Gender lookup is temporarily unavailable`          | Gender provider not configured           |

<Note>
  A transient provider error (`502`) is never billed. An `unknown` verdict from a
  successful lookup **is** billed like any other result.
</Note>

## Credits

Each lookup costs **1 credit**. Billing is per-customer: 1 on the first lookup of
an address, `0` for repeats within the billing window (about 6 months). See
[Credits](/credits) for details.

<ResponseExample>
  ```json 200 Resolved theme={"dark"}
  {
    "email": "jane.doe@example.com",
    "gender": "female",
    "country": "US",
    "probability": 98,
    "credits": 1
  }
  ```

  ```json 200 Unknown theme={"dark"}
  {
    "email": "info@example.com",
    "gender": "unknown",
    "country": null,
    "probability": 0,
    "credits": 1
  }
  ```

  ```json 402 theme={"dark"}
  { "error": "Insufficient credits. Please top up your account." }
  ```
</ResponseExample>

## Bulk (asynchronous)

To label a whole list, submit it as an async job instead of looping this
endpoint. One entrypoint handles every lookup - set `type=gender` - and a webhook
delivers the finished file when it's done.

```bash theme={"dark"}
curl -X POST "https://developer.encrata.com/api/jobs/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "type=gender" \
  -F "download_link=true" \
  -F "file=@list.csv"
```

* Up to **1,000,000 emails per job**, charged **1 credit per email**.
* `download_link=true` returns a `download_url` in the `bulk.completed` webhook; fetch it with your API key.
* Export filters: `all`, `found`.

See the [Bulk Operations guide](/guides/bulk-operations) for the webhook payload,
status checks, and download options.