# Xác định giới tính từ địa chỉ email

> Dùng tín hiệu tên trong email với GenderAPI.io V2. Thử tra cứu trực tiếp, so sánh tùy chọn tập dữ liệu và AI, đồng thời tìm hiểu cách xử lý kết quả không xác định và danh sách email số lượng lớn.

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

Last reviewed: 2026-09-29

## Địa chỉ email cho bạn biết được gì?

Gửi một địa chỉ email đúng cú pháp với type: email. GenderAPI.io tìm tín hiệu tên trong phần đứng trước @, sau đó trả về một kết quả suy luận có cấu trúc. API không xác minh hộp thư, không xác định chủ sở hữu và không xác lập bản dạng giới của người đó.

Khi so khớp với tập dữ liệu, hệ thống tách ra các token ứng viên và có thể thử các chuỗi con trong giới hạn nhất định. Chế độ biệt danh vẫn so khớp theo token nhưng không thêm các ứng viên chuỗi con đó. Nếu có nhiều bản ghi khớp, ứng viên có tổng số lượng lưu trữ lớn nhất sẽ được chọn; không có gì bảo đảm đó là tên riêng mà bạn mong đợi. Hãy kiểm tra data.name và data.match trước khi dùng tên trích xuất được trong hồ sơ liên hệ.

| Ví dụ đầu vào | Cách hiểu |
| --- | --- |
| `alice.smith@example.com` | Phần cục bộ chứa các token có thể là tên. Có thể có kết quả khớp, nhưng chỉ riêng đầu vào không cho biết ứng viên nào sẽ được chọn. |
| `alice+news@example.com` | Khi tra cứu tập dữ liệu, hậu tố sau dấu cộng bị loại khỏi các ứng viên. AI được hướng dẫn bỏ qua hậu tố này, nhưng vẫn nhận giá trị đã gửi. |
| `support@example.com` | Địa chỉ theo vai trò không mang tín hiệu tên cá nhân đáng tin cậy. Đừng gán giới tính của một người cho cả hộp thư dùng chung. |
| `prenses@example.com` | forceToGenderize (tùy chọn) cho phép thử suy luận từ ý nghĩa của biệt danh nếu tập dữ liệu chưa xác định được. Ở chế độ này không cần tên thật. |
| `not-an-email` | Cú pháp không hợp lệ trả về lỗi xác thực, không phải một kết quả không xác định thành công. |

## Gửi yêu cầu tra cứu email từ ứng dụng của bạn

Ví dụ này dùng khóa API hiện có trong tiêu đề Bearer và đặt fallback một cách rõ ràng. Hãy thay địa chỉ mẫu bằng một đầu vào bạn được phép xử lý. Chỉ gửi country khi bạn có ngữ cảnh liên quan; tên miền email không xác định vị trí của một người. Nếu không có quốc gia, hãy bỏ qua trường đó.

Chạy ví dụ trên máy chủ của bạn sau khi đặt GENDERAPI_API_KEY. POST giữ giá trị email ngoài URL của yêu cầu. Kết quả trực tiếp có thể khác với phản hồi minh họa trong bản demo.

Chạy các ví dụ này trên máy chủ của bạn. Đặt GENDERAPI_API_KEY trong biến môi trường của tiến trình bằng khóa API hiện có. Xác nhận meta.access.mode là api_key: khóa không được nhận diện có thể chuyển sang dùng thử theo IP.

Mỗi yêu cầu dự đoán là một thao tác mới bị tính phí, kể cả khi thử lại. Các ví dụ này không tự động thử lại. Kiểm tra trạng thái tính phí trước khi gửi yêu cầu khác.

Với phản hồi JSON HTTP 4xx và 5xx, ví dụ giữ nguyên nội dung lỗi và kết thúc với mã thoát khác 0. Kiểm tra code, action và meta.usage.billing_status trước khi thử lại.

**cURL**

cURL 7.76+ trong shell POSIX. Chạy trong terminal.

```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 tích hợp sẵn. Lưu thành example.mjs và chạy 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+; thư viện chuẩn. Lưu thành example.py và chạy 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+ với tiện ích mở rộng cURL. Lưu thành example.php và chạy 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 client chuẩn. Lưu thành GenderApiExample.java và chạy 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**

Ứng dụng console .NET 8+. Dùng làm Program.cs trong một dự án console, sau đó chạy 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+; thư viện chuẩn. Lưu thành main.go và chạy 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)
    }
}
```

- [Tham chiếu V2 đầy đủ cho email](https://www.genderapi.io/vi/docs/v2/gender-from-email)

## Lưu kết quả cùng với bằng chứng của nó

Một mối liên hệ được suy luận không phải là giới tính do chính người đó tự công bố. Hãy lưu riêng đầu vào gốc, bằng chứng được trả về và mọi thông tin do người đó cung cấp. Kết quả không xác định là một kết quả hợp lệ; không nên biến nó thành một nhóm được đoán trong ứng dụng của bạn.

| Trường | Cách sử dụng |
| --- | --- |
| `data.gender / data.result_status` | Chỉ dùng male hoặc female khi kết quả là identified. Giữ nguyên giá trị JSON null gốc khi kết quả không xác định. |
| `data.name / data.match` | Kiểm tra tên được trả về và ứng viên được chọn. Kết quả khớp theo chuỗi con không chứng minh rằng đầu vào thuộc về người có tên riêng đó. |
| `data.confidence / data.confidence_kind` | Độ tin cậy nằm trên thang từ 0 đến 1 hoặc là null. observed_frequency dựa trên số lượng đã lưu; model_reported là điểm do AI đưa ra. Hãy đánh giá ngưỡng riêng cho từng loại. |
| `data.source / data.sample_count` | Phân biệt dataset, ai và none. Kết quả AI không có số lượng mẫu đã lưu. Số lượng mẫu không phải là điểm độ chính xác đã đo. |
| `meta.access.mode` | Xác nhận api_key với tích hợp dùng tài khoản. Khóa bị thiếu hoặc không được nhận diện có thể chuyển sang dùng thử theo IP dùng chung. |
| `meta.usage` | Đọc charged_credits và billing_status. Kết quả không xác định thành công vẫn bị tính phí. Mất phản hồi không chứng minh rằng yêu cầu được miễn phí. |

- [Trường phản hồi và kết quả không xác định](https://www.genderapi.io/vi/docs/v2/responses)
- [Giải thích về độ chính xác và độ tin cậy](https://www.genderapi.io/vi/accuracy-methodology)
- [Nguồn dữ liệu và hồ sơ tập dữ liệu có ghi ngày](https://www.genderapi.io/vi/data-provenance)

## Chọn khi nào dùng AI

forceToGenderize là tùy chọn cho tên, địa chỉ email và tên người dùng. Khi bật trường này, hãy bỏ qua ai_mode hoặc dùng fallback; off và always xung đột với nó và trả về 422. Chỉ cần số dư ban đầu dương là đủ để bắt đầu một yêu cầu, kể cả khi lần tính phí cuối cùng làm số dư xuống dưới 0.

Chế độ biệt danh có thể trả về giới tính cùng name: null. Chế độ này cũng có thể trả về kết quả không xác định. Cả AI dự phòng thông thường lẫn suy luận biệt danh đều không bảo đảm câu trả lời đúng hoặc khác null.

| Tùy chọn yêu cầu | Cách hoạt động | Tín dụng cho một lần tra cứu thành công |
| --- | --- | --- |
| options.ai_mode: off | Chỉ dùng tập dữ liệu. | 1, kể cả kết quả không xác định |
| options.ai_mode: fallback | Tra tập dữ liệu trước, sau đó dùng AI thông thường khi không có giới tính được trả về. Đây là mặc định cho yêu cầu đơn lẻ. | Tổng cộng 1, đã gồm AI dự phòng |
| options.ai_mode: always | Dùng AI trực tiếp. | 2 |
| forceToGenderize: true | Tra tập dữ liệu trước, sau đó cho phép AI diễn giải biệt danh cá nhân hoặc bí danh, kể cả khi không có tên thật. | 1 khi tập dữ liệu cho ra kết quả; tổng cộng 2 nếu dùng AI |

- [Tùy chọn AI và suy luận biệt danh](https://www.genderapi.io/vi/docs/v2/ai-options)
- [Tín dụng và mức sử dụng](https://www.genderapi.io/vi/docs/v2/credits-and-usage)

## Xử lý danh sách email theo lô

Dùng POST /api/v2/gender/batch với mảng items gồm các mục type: email. Truy cập bằng khóa API đã đăng ký hỗ trợ tối đa 50 mục; dùng thử theo IP hỗ trợ tối đa 10 mục. Giữ một id duy nhất cho mỗi mục để có thể ghép kết quả trở lại dòng gốc. Phản hồi cũng giữ nguyên thứ tự đầu vào và trả về index.

Các mục trong lô mặc định chỉ dùng tập dữ liệu. Đặt options.ai_mode: fallback cho từng mục cần AI dự phòng thông thường. Hai mục fallback thành công tốn tổng cộng 2 tín dụng, kể cả kết quả không xác định; một yêu cầu HTTP không tương đương một tín dụng dự đoán.

Hãy kiểm tra từng mục, kể cả khi lô trả về HTTP 200. Lưu các kết quả thành công và không xác định, sau đó xem lại lỗi và việc tính phí đã được xác nhận trước khi gửi lại các mục thất bại. Không gửi lại toàn bộ một lô đã thành công sau khi hết thời gian chờ mà chưa kiểm tra kết quả tính phí.

- [Ví dụ lô, giới hạn và lỗi một phần](https://www.genderapi.io/vi/docs/v2/batch)

## Hiểu rõ dữ liệu bạn gửi đi

Bản demo trực tiếp chỉ gửi giá trị đã nhập đến GenderAPI.io khi bạn chủ động gửi. Nếu AI được gọi, type, value và ngữ cảnh quốc gia đã gửi sẽ được chuyển đến dịch vụ suy luận đã được cấu hình. Để chỉ dự đoán bằng tập dữ liệu, hãy dùng options.ai_mode: off mà không có forceToGenderize trong tích hợp của bạn.

Chính sách quyền riêng tư, thỏa thuận xử lý dữ liệu và danh sách bên xử lý dữ liệu phụ mô tả các điều kiện xử lý đã công bố. Kết quả là một mối liên hệ được suy luận; hãy ưu tiên thông tin do chính người đó cung cấp. Không dùng kết quả làm cơ sở cho các quyết định có ảnh hưởng quan trọng đến một cá nhân.

- [Chính sách quyền riêng tư](https://www.genderapi.io/vi/privacy-policy)
- [Thỏa thuận xử lý dữ liệu](https://www.genderapi.io/vi/data-processing-agreement)
- [Danh sách bên xử lý dữ liệu phụ](https://www.genderapi.io/vi/subprocessors)

## API có thể trích xuất tên từ địa chỉ email không?

API có thể trả về một tên ứng viên khi phần cục bộ chứa tín hiệu dùng được. Có thể có kết quả khớp theo token hoặc chuỗi con, vì vậy hãy kiểm tra data.match. Kết quả không chứng minh tên riêng của chủ hộp thư.

## info@ hoặc support@ có trả về giới tính không?

Địa chỉ theo vai trò dùng chung thường không có bằng chứng về tên cá nhân. Kết quả không xác định là hợp lệ. Không nên coi AI hoặc chế độ biệt danh là cách xác minh những người dùng một hộp thư chung.

## Kết quả email không xác định có tốn tín dụng không?

Có. Một lần tra cứu email thông thường thành công tốn 1 tín dụng, kể cả khi dùng fallback và khi kết quả không xác định. Suy luận biệt danh bắt buộc tốn 1 tín dụng khi tập dữ liệu cho ra kết quả, hoặc tổng cộng 2 tín dụng nếu dùng AI. Lỗi có kết quả tính phí riêng trong meta.usage.

## Tên miền email có bị loại bỏ trước khi AI xử lý không?

Không có cam kết loại bỏ như vậy. Ứng viên trong tập dữ liệu lấy từ phần cục bộ, còn AI nhận giá trị đã gửi và được hướng dẫn bỏ qua tên miền cùng hậu tố sau dấu cộng. Hãy dùng chế độ chỉ dùng tập dữ liệu nếu quy trình của bạn yêu cầu điều đó.