# 根据电子邮箱地址判断性别

> 使用 GenderAPI.io V2 利用电子邮箱地址中的姓名信号。试用实时请求，比较数据集与 AI 选项，并了解如何处理未知结果和电子邮箱地址列表。

Canonical HTML: https://www.genderapi.io/zh/determine-gender-from-email

Last reviewed: 2026-09-29

## 电子邮箱地址能透露什么？

请使用 type: email 发送语法有效的电子邮箱地址。GenderAPI.io 会在 @ 之前的部分查找姓名信号，然后返回结构化的预测。系统不会验证该邮箱，不会把它与持有人关联起来，也不会确定持有人的性别认同。

数据集匹配会从地址的各个部分提取候选项，并可能检查有限的子字符串。昵称模式保留按完整部分进行的匹配，但不会添加这些基于子字符串的候选项。如果有多条记录匹配，会选择存储总计数最大的候选项，而它不一定是想要的名字。在把提取出的名字用于联系人记录之前，请检查 data.name 和 data.match。

| 输入示例 | 解读 |
| --- | --- |
| `alice.smith@example.com` | 本地部分包含可能的姓名组成部分。可能会有匹配，但仅凭输入本身无法确定会选中哪个候选项。 |
| `alice+news@example.com` | 数据集查询会在生成候选项时去掉加号之后的后缀。AI 会被要求忽略该后缀，但收到的是提交的原值。 |
| `support@example.com` | 职能地址无法提供可靠的个人姓名信号。不要把某个人的性别套用到整个共享邮箱上。 |
| `prenses@example.com` | 当数据集无法得出结果时，forceToGenderize 选项允许根据昵称的含义进行尝试。此模式不需要真实姓名。 |
| `not-an-email` | 语法无效时会返回验证错误，而不是成功完成的未知结果。 |

## 从您的应用发送电子邮箱地址请求

此示例在 Bearer 请求头中使用您现有的 API 密钥，并显式设置 fallback。请把示例地址替换为您有权处理的输入。只有在掌握相关背景时才提供 country；电子邮箱域名并不能说明一个人身在何处。没有国家/地区背景时，请省略该字段。

设置 GENDERAPI_API_KEY 后，请在您的服务器上运行示例。使用 POST 时，电子邮箱地址不会出现在请求 URL 中。实时结果可能与演示中的示例响应不同。

请在您的服务器上运行这些示例。在进程环境中将 GENDERAPI_API_KEY 设置为您现有的 API 密钥。请确认 meta.access.mode 为 api_key：无法识别的密钥可能会转为使用 IP 试用。

每个预测请求（包括重试）都是一次新的计费操作。这些示例不会自动重试。发送下一个请求之前，请先检查计费状态。

对于 HTTP 4xx 和 5xx JSON 响应，示例会保留错误响应体并以非零状态退出。重试前请检查 code、action 和 meta.usage.billing_status。

**cURL**

cURL 7.76+，在 POSIX shell 中运行。在终端中运行。

```bash
curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "email",
  "value": "alice.smith@example.com",
  "country": "US",
  "options": {
    "ai_mode": "fallback"
  }
}'
```

**JavaScript / Node.js**

Node.js 22+；内置 fetch。保存为 example.mjs，然后运行 node example.mjs。

```javascript
// Server-side Node.js. Save as example.mjs.
const apiKey = process.env.GENDERAPI_API_KEY;
if (!apiKey) throw new Error("Set GENDERAPI_API_KEY");
const body = {
  "type": "email",
  "value": "alice.smith@example.com",
  "country": "US",
  "options": {
    "ai_mode": "fallback"
  }
};

const response = await fetch("https://api.genderapi.io/api/v2/gender", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000),
  redirect: "error",
});
const raw = await response.text();
if (!(response.headers.get("content-type") ?? "").includes("json")) {
  throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`);
}
const result = JSON.parse(raw); // Also accepts application/problem+json.
if (!response.ok) {
  console.error(`HTTP ${response.status}`, result);
  process.exitCode = 1; // A retry is a new operation; inspect billing first.
} else {
  console.log(JSON.stringify(result, null, 2));
  // For batches, inspect every item: HTTP 200 may contain item errors.
}
```

**Python**

Python 3.10+；标准库。保存为 example.py，然后运行 python3 example.py。

```python
import json
import os
import sys
import urllib.error
import urllib.request

api_key = os.environ.get("GENDERAPI_API_KEY")
if not api_key:
    raise RuntimeError("Set GENDERAPI_API_KEY")
body = json.loads("{\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"country\":\"US\",\"options\":{\"ai_mode\":\"fallback\"}}")

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(
    "https://api.genderapi.io/api/v2/gender",
    method="POST",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + api_key,
        "Content-Type": "application/json",
    },
)
opener = urllib.request.build_opener(NoRedirect())
try:
    response = opener.open(request, timeout=30)
except urllib.error.HTTPError as error:
    response = error  # Keep the Problem Details body on non-2xx responses.
with response:
    status = response.status
    raw = response.read().decode("utf-8")
    if "json" not in response.headers.get("Content-Type", ""):
        raise RuntimeError(f"HTTP {status}: expected a JSON response")
    result = json.loads(raw)
print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout)
if not 200 <= status < 300:
    sys.exit(1)  # Inspect code, action and billing before retrying.
# For batches, inspect every item even when HTTP status is 200.
```

**PHP**

PHP 8+，需要 cURL 扩展。保存为 example.php，然后运行 php example.php。

```php
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"email","value":"alice.smith@example.com","country":"US","options":{"ai_mode":"fallback"}}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
]);
$raw = curl_exec($ch);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: '';
curl_close($ch);
if (strpos($contentType, 'json') === false) {
    throw new RuntimeException("HTTP $status: expected a JSON response");
}
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
$output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL;
if ($status < 200 || $status >= 300) {
    fwrite(STDERR, $output); // Preserve the Problem Details body.
    exit(1);
}
echo $output;
// For batches, inspect every item; HTTP 200 can contain item errors.
```

**Java**

Java 17+；标准 HTTP 客户端。保存为 GenderApiExample.java，然后运行 java GenderApiExample.java。

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class GenderApiExample {
    private static String requiredEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name);
        return value;
    }

    public static void main(String[] args) throws Exception {
        String apiKey = requiredEnv("GENDERAPI_API_KEY");
        String body = "{\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"country\":\"US\",\"options\":{\"ai_mode\":\"fallback\"}}";
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .followRedirects(HttpClient.Redirect.NEVER)
            .build();
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/gender"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        if (!response.headers().firstValue("content-type").orElse("").contains("json")) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON");
        }
        // JSON text; parse with your application's JSON library when integrating.
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            System.err.println(response.body()); // Includes Problem Details.
            System.exit(1);
        }
        System.out.println(response.body());
        // For batches, inspect each item's data or error, including on HTTP 200.
    }
}
```

**C# / .NET**

.NET 8+ 控制台应用。在控制台项目中作为 Program.cs 使用，然后运行 dotnet run。

```csharp
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

string RequiredEnv(string name) =>
    !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name))
        ? Environment.GetEnvironmentVariable(name)!
        : throw new InvalidOperationException($"Set {name}");

var apiKey = RequiredEnv("GENDERAPI_API_KEY");
using var handler = new HttpClientHandler { AllowAutoRedirect = false };
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.genderapi.io/api/v2/gender");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"country\":\"US\",\"options\":{\"ai_mode\":\"fallback\"}}", Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
var raw = await response.Content.ReadAsStringAsync();
if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false))
    throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON");
using var result = JsonDocument.Parse(raw);
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(result.RootElement); // Preserve Problem Details.
    Environment.ExitCode = 1;
}
else
{
    Console.WriteLine(result.RootElement);
    // For batches, inspect every item even on HTTP 200.
}
```

**Go**

Go 1.22+；标准库。保存为 main.go，然后运行 go run main.go。

```go
package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requiredEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("Set " + name) }
    return value
}

func run() error {
    apiKey := requiredEnv("GENDERAPI_API_KEY")
    body := "{\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"country\":\"US\",\"options\":{\"ai_mode\":\"fallback\"}}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender", strings.NewReader(body))
    if err != nil { return err }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Content-Type", "application/json")
    client := &http.Client{
        Timeout: 30 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    response, err := client.Do(request)
    if err != nil { return err }
    defer response.Body.Close()
    raw, err := io.ReadAll(response.Body)
    if err != nil { return err }
    if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) {
        return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode)
    }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw)
    }
    fmt.Println(string(raw))
    // For batches, inspect every item even on HTTP 200.
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling.
        os.Exit(1)
    }
}
```

- [电子邮箱地址的完整 V2 参考](https://www.genderapi.io/zh/docs/v2/gender-from-email)

## 将结果与其依据一起保存

推断出的关联并不是本人自述的性别。请把原始输入、返回的依据以及本人提供的信息分开保存。未知结果是有效的结果，不应在您的应用中变成一个猜测出来的类别。

| 字段 | 使用方式 |
| --- | --- |
| `data.gender / data.result_status` | 只有在 identified 时才使用 male 或 female。结果未知时，请保留 JSON 原生的 null 值。 |
| `data.name / data.match` | 检查返回的名字和所选的候选项。子字符串匹配并不能证明该输入属于拥有这个名字的人。 |
| `data.confidence / data.confidence_kind` | 置信度为 0–1 之间的值或 null。observed_frequency 来自存储的计数；model_reported 是 AI 给出的值。请针对每种类型分别评估阈值。 |
| `data.source / data.sample_count` | 区分 dataset、ai 和 none。AI 结果没有存储的样本数。样本数并不是实测的准确率。 |
| `meta.access.mode` | 在账户集成中，请确认值为 api_key。缺失或无法识别的密钥可能会转为使用共享的 IP 试用。 |
| `meta.usage` | 读取 charged_credits 和 billing_status。成功完成的未知结果同样计费。响应丢失并不能证明该请求是免费的。 |

- [响应字段与未知结果](https://www.genderapi.io/zh/docs/v2/responses)
- [准确性与置信度说明](https://www.genderapi.io/zh/accuracy-methodology)
- [数据来源与注明日期的数据库概况](https://www.genderapi.io/zh/data-provenance)

## 决定何时使用 AI

forceToGenderize 对姓名、电子邮箱地址和用户名都是可选的。启用时，请省略 ai_mode 或使用 fallback；off 和 always 不能与此选项组合，否则会返回 422。起始余额为正即可发起请求，即使最终扣费后余额变为负数。

昵称模式可能在 name: null 的同时返回性别，也可能得到未知结果。无论是普通的 AI 回退还是昵称解读，都不能保证答案正确或返回非 null 的值。

| 请求选项 | 行为 | 每次成功查询消耗的积分 |
| --- | --- | --- |
| options.ai_mode: off | 仅使用数据集。 | 1，未知结果也是如此 |
| options.ai_mode: fallback | 先查询数据集；如果没有返回性别，再使用普通的 AI。这是单个请求的默认值。 | 总共 1，包括 AI 回退 |
| options.ai_mode: always | 直接使用 AI。 | 2 |
| forceToGenderize: true | 先查询数据集，然后允许 AI 解读个人昵称或别名，即使没有真实名字也可以。 | 数据集得出结果时为 1；使用 AI 时总共为 2 |

- [AI 选项与昵称解读](https://www.genderapi.io/zh/docs/v2/ai-options)
- [积分与用量](https://www.genderapi.io/zh/docs/v2/credits-and-usage)

## 批量处理电子邮箱地址列表

请使用 POST /api/v2/gender/batch，并发送由 type: email 条目组成的 items 数组。使用已注册的 API 密钥时最多可包含 50 个条目，使用 IP 试用时最多 10 个。请为每个条目保留唯一的 id，以便把结果对应到原始行。响应也会保持输入顺序并给出 index。

默认情况下，批量请求中的条目只使用数据集。需要普通 AI 回退的条目，请分别设置 options.ai_mode: fallback。两个使用 fallback 的成功条目总共消耗 2 个积分，即使结果未知也是如此；一个 HTTP 请求并不等于每次预测只消耗一个积分。

即使批量请求返回 HTTP 200，也请逐条检查。先保存成功的结果和未知结果，再检查错误和已确认的计费，然后才重新发送失败的条目。发生超时后，请先检查计费，不要直接重新发送整个成功的批量请求。

- [批量请求示例、限制与部分失败](https://www.genderapi.io/zh/docs/v2/batch)

## 了解您发送了什么

实时演示只会在您提交时，才把输入的值发送给 GenderAPI.io。如果调用了 AI，提交的 type、value 和国家/地区背景会被发送给已配置的推断服务。如需仅基于数据集的预测，请在您的集成中使用 options.ai_mode: off，且不要使用 forceToGenderize。

隐私政策、数据处理协议和次级处理方名单说明了已公布的处理条款。结果只是推断出的关联，本人的自述优先。请不要把它作为对个人有重大影响的决策依据。

- [隐私政策](https://www.genderapi.io/zh/privacy-policy)
- [数据处理协议](https://www.genderapi.io/zh/data-processing-agreement)
- [次级处理方](https://www.genderapi.io/zh/subprocessors)

## API 能从电子邮箱地址中提取名字吗？

当本地部分包含可用的信号时，它可以返回一个姓名候选项。可能按完整部分匹配，也可能按子字符串匹配，因此请检查 data.match。该结果并不能说明邮箱持有人的名字。

## info@ 或 support@ 这类地址会返回性别吗？

共享的职能地址通常不提供个人姓名的依据。未知结果是有效的。不应把 AI 或昵称模式当作对使用共享邮箱的人的确认。

## 电子邮箱地址的未知结果会消耗积分吗？

会。一次成功的普通电子邮箱地址请求消耗 1 个积分，包括 AI 回退和未知结果。强制昵称解读在数据集得出结果时消耗 1 个积分，使用 AI 时总共消耗 2 个积分。出错时，扣费情况会在 meta.usage 中单独说明。

## 在 AI 处理地址之前，电子邮箱域名会被去掉吗？

不作保证。数据集候选项来自本地部分，而 AI 收到的是提交的原值，并被要求忽略域名和加号之后的后缀。如果您的工作流程需要，请使用仅数据集模式。