# API v2를 사용한 이메일 주소의 성별

> 이메일 이름 신호에서 성별을 추론하려면 GenderAPI v2를 사용하세요. 요청 및 응답 예시, 검증, 알 수 없는 결과 및 AI 옵션이 포함됩니다.

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

Last reviewed: 2026-09-25

## 요청을 보내기 전에

JSON를 POST https://api.genderapi.io/api/v2/gender로 보냅니다. Authorization: Bearer YOUR_API_KEY 및 Content-Type: application/json에서 기존 API 키를 사용하세요. 모든 요청은 독립적으로 처리됩니다.

코드 예시에서 언어를 선택하세요. 실행하기 전에 프로세스 환경에서 GENDERAPI_API_KEY를 설정하십시오. 누락되거나 인식되지 않는 키는 공유된 IP 평가판을 사용할 수 있으므로 계정을 통합할 때 meta.access.mode가 api_key인지 확인하세요.

- [인증 및 평가판 액세스](https://www.genderapi.io/ko/docs/v2/authentication)
- [모든 요청 매개변수](https://www.genderapi.io/ko/docs/v2/request-parameters)

## 이메일 주소의 성별

type: email를 사용하세요. API는 주소에서 사용 가능한 이름 신호를 찾습니다. 공유 받은 편지함과 불투명한 로컬 부분은 알 수 없는 결과를 생성할 수 있습니다. forceToGenderize는 여기서도 선택 사항입니다. 실제 이름이 없어도 별칭에서 AI 추론을 허용합니다.

서버에서 다음 예제를 실행하세요. 프로세스 환경에서 GENDERAPI_API_KEY를 기존 API 키로 설정합니다. meta.access.mode가 api_key인지 확인하세요. 인식되지 않은 키는 IP 평가판으로 대체될 수 있습니다.

모든 예측 요청은 재시도를 포함하여 청구 가능한 새로운 작업입니다. 이러한 예제는 자동으로 재시도하지 않습니다. 다른 요청을 보내기 전에 청구 상태를 확인하세요.

HTTP 4xx 및 5xx JSON 응답은 오류 본문을 보존하고 0이 아닌 종료 상태를 반환합니다. 다시 시도하기 전에 code, action 및 meta.usage.billing_status를 확인하세요.

**cURL**

POSIX 셸의 cURL 7.76+. 터미널에서 실행하세요.

```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/ko/docs/v2/responses)

## 이메일 검증 및 이름 신호

value는 구문상 유효한 이메일 주소여야 합니다. 잘못된 구문은 청구 전에 HTTP 422를 반환합니다. 구문 유효성 검사에서는 사서함이 존재하거나 특정 사람에게 속해 있는지 확인하지 않습니다.

주소에서 인식 가능한 개인 이름이 데이터 세트와 일치할 수 있습니다. 공유 사서함, 역할 주소 및 불투명 로컬 부분은 성별(null)을 반환할 수 있습니다. 기본적으로 해결되지 않은 단일 조회는 성공적인 알 수 없는 결과를 포함하여 총 1크레딧에 대해 일반 AI 대체를 사용합니다.

데이터세트가 해결되지 않은 경우 별명 인식 AI 추론을 원하는 경우 forceToGenderize: true를 사용하세요. 해결된 데이터 세트 결과에 대해 1크레딧이 필요하고, AI를 사용하는 경우 총 2크레딧이 필요합니다. API는 여전히 null를 반환할 수 있습니다. 이메일 도메인은 그 사람의 위치를 증명하는 것이 아닙니다. 관련 상황이 알려진 경우에만 국가를 제공합니다.

## 관련 가이드

- [AI 모드 및 forceToGenderize](https://www.genderapi.io/ko/docs/v2/ai-options)
- [일괄 예측](https://www.genderapi.io/ko/docs/v2/batch)
- [크레딧 및 사용량](https://www.genderapi.io/ko/docs/v2/credits-and-usage)
- [오류 및 재시도](https://www.genderapi.io/ko/docs/v2/errors-and-retries)