# الجنس من عنوان بريد إلكتروني مع API v2

> استخدم GenderAPI v2 لاستنتاج الجنس من إشارة اسم البريد الإلكتروني. يتضمن أمثلة الطلب والاستجابة والتحقق من الصحة والنتائج غير المعروفة وخيارات الذكاء الاصطناعي.

Canonical HTML: https://www.genderapi.io/ar/docs/v2/gender-from-email

Last reviewed: 2026-09-25

## قبل إرسال الطلب

أرسل JSON إلى POST https://api.genderapi.io/api/v2/gender. استخدم مفتاح API الموجود لديك في Authorization: Bearer YOUR_API_KEY وContent-Type: application/json. تتم معالجة كل طلب بشكل مستقل.

اختر لغتك في مثال الكود. قم بتعيين GENDERAPI_API_KEY في بيئة العملية قبل تشغيله. يمكن للمفاتيح المفقودة أو غير المعروفة استخدام النسخة التجريبية المشتركة من IP، لذا تأكد من أن meta.access.mode هو api_key عند دمج الحساب.

- [المصادقة والوصول التجريبي](https://www.genderapi.io/ar/docs/v2/authentication)
- [جميع معلمات الطلب](https://www.genderapi.io/ar/docs/v2/request-parameters)

## الجنس من عنوان البريد الإلكتروني

استخدم type: email. يبحث API عن إشارة اسم قابلة للاستخدام في العنوان. قد تؤدي صناديق البريد الوارد المشتركة والأجزاء المحلية غير الشفافة إلى نتيجة غير معروفة. forceToGenderize اختياري هنا أيضًا؛ فهو يسمح بالاستدلال بالذكاء الاصطناعي من اسم مستعار حتى بدون اسم حقيقي.

قم بتشغيل هذه الأمثلة على الخادم الخاص بك. قم بتعيين 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. قم بالتشغيل في جهازك الطرفي.

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

**JavaScript / Node.js**

Node.js 22+; جلب مدمج. احفظ باسم 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"
};

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

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"}', 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\"}";
        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\"}", 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\"}"
    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)
    }
}
```

## مثال للرد

توضح هذه الاستجابة الاصطناعية شكل JSON، وليست دقة مقاسة أو نتيجة حية مضمونة. يُظهر الوصول التجريبي إلى IP؛ تقارير عملية تمت مصادقتها عن حقول الحصص التجريبية فقط meta.access.mode: api_key وnull. اقرأ بيانات الاستدلال وmeta.usage لنتائج فواتير العملية.

```json
{
  "data": {
    "input": {
      "type": "email",
      "value": "alice.smith@example.com",
      "country": "US"
    },
    "name": "alice",
    "gender": "female",
    "country": "US",
    "confidence": 0.9,
    "confidence_kind": "observed_frequency",
    "sample_count": 100,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "alice",
      "method": "normalized",
      "scope": "country",
      "country": "US"
    }
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 9,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}
```

- [مجالات الاستجابة والثقة](https://www.genderapi.io/ar/docs/v2/responses)

## التحقق من صحة البريد الإلكتروني وإشارات الاسم

يجب أن يكون value عنوان بريد إلكتروني صالحًا من الناحية التركيبية. يقوم بناء جملة غير صالح بإرجاع HTTP 422 قبل إعداد الفواتير. لا يثبت التحقق من صحة بناء الجملة أن صندوق البريد موجود أو ينتمي إلى شخص معين.

قد يتطابق الاسم الشخصي الذي يمكن التعرف عليه في العنوان مع مجموعة البيانات. يمكن لصناديق البريد المشتركة وعناوين الأدوار والأجزاء المحلية غير الشفافة إرجاع الجنس: null. افتراضيًا، يستخدم البحث الفردي الذي لم يتم حله احتياطي الذكاء الاصطناعي العادي لإجمالي رصيد واحد، بما في ذلك نتيجة ناجحة غير معروفة.

استخدم forceToGenderize: true إذا كنت تريد استنتاج الذكاء الاصطناعي المدرك للألقاب عندما لا يتم حل مجموعة البيانات. يكلف هذا رصيدًا واحدًا لنتيجة مجموعة البيانات التي تم حلها أو مجموعتين إذا تم استخدام الذكاء الاصطناعي. قد يستمر API في إرجاع null. نطاق البريد الإلكتروني ليس دليلاً على موقع الشخص؛ تزويد الدولة فقط عندما يكون السياق ذو الصلة معروفًا.

## أدلة ذات صلة

- [أوضاع الذكاء الاصطناعي وforceToGenderize](https://www.genderapi.io/ar/docs/v2/ai-options)
- [توقعات الدفعة](https://www.genderapi.io/ar/docs/v2/batch)
- [الاعتمادات والاستخدام](https://www.genderapi.io/ar/docs/v2/credits-and-usage)
- [الأخطاء وإعادة المحاولة](https://www.genderapi.io/ar/docs/v2/errors-and-retries)