# Sukupuolen arviointi sähköpostiosoitteesta

> Hyödynnä sähköpostiosoitteen nimisignaalia GenderAPI.io V2:lla. Kokeile reaaliaikaista hakua, vertaa tietoaineiston ja tekoälyn asetuksia ja opi käsittelemään tuntemattomat tulokset ja suuret sähköpostiluettelot.

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

Last reviewed: 2026-09-30

## Mitä sähköpostiosoite voi kertoa?

Lähetä syntaksiltaan kelvollinen sähköpostiosoite asetuksella type: email. GenderAPI.io etsii nimisignaalia @-merkkiä edeltävästä osasta ja palauttaa sitten jäsennellyn päätelmän. Se ei tarkista postilaatikkoa, tunnista sen omistajaa eikä määritä kyseisen henkilön sukupuoli-identiteettiä.

Tietoaineiston haku muodostaa ehdokkaat osoitteen osista ja voi kokeilla rajattua määrää merkkijonon osia. Lempinimitila säilyttää kokonaisten osien haun mutta ei lisää näitä merkkijonon osista muodostettuja ehdokkaita. Jos useampi tietue vastaa hakua, valituksi tulee ehdokas, jonka tallennettu kokonaismäärä on suurin; se ei välttämättä ole tarkoitettu etunimi. Tarkista data.name ja data.match ennen kuin käytät poimittua nimeä yhteystietueessa.

| Esimerkkisyöte | Miten sitä tulkitaan |
| --- | --- |
| `alice.smith@example.com` | Paikallinen osa sisältää mahdollisia nimen osia. Osuma on mahdollinen, mutta pelkkä syöte ei ratkaise, mikä ehdokas valitaan. |
| `alice+news@example.com` | Tietoaineiston haku poistaa plus-merkin jälkeisen päätteen ehdokkaistaan. Tekoälyä ohjeistetaan jättämään se huomiotta, mutta se saa lähetetyn arvon. |
| `support@example.com` | Rooliosoite ei anna luotettavaa henkilönnimen signaalia. Älä määritä koko jaetulle postilaatikolle yhden henkilön sukupuolta. |
| `prenses@example.com` | Valinnainen forceToGenderize sallii yrityksen lempinimen merkityksen perusteella, jos tietoaineisto ei tuota tulosta. Tässä tilassa todellista nimeä ei tarvita. |
| `not-an-email` | Virheellinen syntaksi palauttaa validointivirheen, ei onnistunutta tuntematonta tulosta. |

## Lähetä sähköpostihaku sovelluksestasi

Esimerkki käyttää nykyistä API-avaintasi Bearer-otsakkeessa ja erikseen valittua fallback-tilaa. Korvaa esimerkkiosoite syötteellä, jota sinulla on lupa käsitellä. Anna country vain, kun sinulla on asiaankuuluva konteksti; sähköpostin verkkotunnus ei kerro, missä henkilö on. Jätä kenttä pois, jos maakontekstia ei ole.

Suorita esimerkki palvelimellasi, kun GENDERAPI_API_KEY on asetettu. POST pitää sähköpostiosoitteen poissa pyynnön URL-osoitteesta. Reaaliaikainen tulos voi poiketa demon havainnollistavasta vastauksesta.

Suorita esimerkit palvelimellasi. Aseta prosessin ympäristömuuttujan GENDERAPI_API_KEY arvoksi nykyinen API-avaimesi. Varmista, että meta.access.mode on api_key: tunnistamaton avain voi siirtää pyynnön IP-kokeiluun.

Jokainen ennustepyyntö on uusi laskutettava toiminto, myös uudelleenyritys. Nämä esimerkit eivät yritä uudelleen automaattisesti. Tarkista laskutuksen tila ennen uuden pyynnön lähettämistä.

HTTP 4xx- ja 5xx-JSON-vastauksissa esimerkit säilyttävät virherungon ja palauttavat nollasta poikkeavan poistumiskoodin. Tarkista code, action ja meta.usage.billing_status ennen uutta yritystä.

**cURL**

cURL 7.76+ POSIX-komentotulkissa. Suorita päätteessä.

```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+; sisäänrakennettu fetch. Tallenna nimellä example.mjs ja suorita 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+; standardikirjasto. Tallenna nimellä example.py ja suorita 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-laajennuksella. Tallenna nimellä example.php ja suorita 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+; standardikirjaston HTTP-asiakas. Tallenna nimellä GenderApiExample.java ja suorita 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+ -konsolisovellus. Käytä konsoliprojektissa nimellä Program.cs ja suorita sitten 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+; standardikirjasto. Tallenna nimellä main.go ja suorita 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:n täydellinen sähköpostiviite](https://www.genderapi.io/fi/docs/v2/gender-from-email)

## Säilytä tulos ja sen perusteet yhdessä

Päätelty yhteys ei ole henkilön itse ilmoittama sukupuoli. Säilytä alkuperäinen syöte, palautetut perusteet ja henkilön itse antamat tiedot erillään. Tuntematon tulos on kelvollinen tulos, eikä siitä pidä tehdä sovelluksessasi arvattua luokkaa.

| Kenttä | Miten sitä käytetään |
| --- | --- |
| `data.gender / data.result_status` | Käytä arvoa male tai female vain, kun tulos on identified. Säilytä alkuperäinen JSON null -arvo, kun tulos on unknown. |
| `data.name / data.match` | Tarkista palautettu nimi ja valittu ehdokas. Osuma merkkijonon osaan ei todista, että syöte kuuluu henkilölle, jolla on kyseinen etunimi. |
| `data.confidence / data.confidence_kind` | Luottamusarvo on väliltä 0–1 tai null. observed_frequency perustuu tallennettuihin määriin; model_reported on tekoälyn pistemäärä. Arvioi kynnysarvot kummallekin tyypille erikseen. |
| `data.source / data.sample_count` | Erota arvot dataset, ai ja none. Tekoälytuloksilla ei ole tallennettua otoskokoa. Otoskoko ei ole mitattu tarkkuus. |
| `meta.access.mode` | Varmista tilin integraatiossa, että arvo on api_key. Puuttuva tai tunnistamaton avain voi sen sijaan käyttää yhteistä IP-kokeilua. |
| `meta.usage` | Lue charged_credits ja billing_status. Onnistunut tuntematon tulos veloitetaan. Kadonnut vastaus ei osoita, että pyyntö oli maksuton. |

- [Vastauskentät ja tuntemattomat tulokset](https://www.genderapi.io/fi/docs/v2/responses)
- [Tarkkuus ja luottamusarvo selitettynä](https://www.genderapi.io/fi/accuracy-methodology)
- [Tietolähteet ja päivätty tietoaineistoprofiili](https://www.genderapi.io/fi/data-provenance)

## Päätä, milloin tekoälyä käytetään

forceToGenderize on valinnainen nimille, sähköpostiosoitteille ja käyttäjänimille. Kun se on käytössä, jätä ai_mode pois tai käytä arvoa fallback; off ja always ovat ristiriidassa sen kanssa ja palauttavat 422-virheen. Positiivinen alkusaldo riittää pyynnön aloittamiseen, vaikka lopullinen veloitus painaisi saldon negatiiviseksi.

Lempinimitila voi palauttaa sukupuolen, vaikka tuloksessa on name: null. Se voi myös palauttaa tuntemattoman tuloksen. Tavallinen tekoäly varalla ja lempinimipäättely eivät takaa oikeaa vastausta eivätkä muuta kuin null-arvoista vastausta.

| Pyynnön asetus | Toiminta | Krediitit onnistuneesta hausta |
| --- | --- | --- |
| options.ai_mode: off | Käyttää vain tietoaineistoa. | 1, myös tuntemattomasta tuloksesta |
| options.ai_mode: fallback | Hakee ensin tietoaineistosta ja käyttää tavallista tekoälyä, jos sukupuolta ei saada. Tämä on yksittäisen pyynnön oletus. | Yhteensä 1, tekoäly varalla mukaan lukien |
| options.ai_mode: always | Käyttää suoraan tekoälyä. | 2 |
| forceToGenderize: true | Hakee ensin tietoaineistosta ja sallii sitten tekoälyn tulkita henkilökohtaisen lempinimen tai aliaksen myös ilman todellista etunimeä. | 1 tietoaineistosta ratkaistusta tuloksesta; yhteensä 2, jos tekoälyä käytetään |

- [Tekoälyasetukset ja lempinimipäättely](https://www.genderapi.io/fi/docs/v2/ai-options)
- [Krediitit ja käyttö](https://www.genderapi.io/fi/docs/v2/credits-and-usage)

## Käsittele sähköpostiluettelo erissä

Käytä reittiä POST /api/v2/gender/batch ja items-taulukkoa, jonka kohteissa on type: email. Rekisteröidyllä API-avaimella erässä voi olla enintään 50 kohdetta, IP-kokeilussa enintään 10. Anna jokaiselle kohteelle yksilöllinen id, jotta tulokset voidaan yhdistää takaisin alkuperäiseen riviin. Vastaus säilyttää myös syötteiden järjestyksen ja ilmoittaa index-arvon.

Eräpyynnön kohteet käyttävät oletuksena vain tietoaineistoa. Aseta options.ai_mode: fallback jokaiseen kohteeseen, jossa tavallista tekoälyä tarvitaan varalla. Kaksi onnistunutta fallback-kohdetta maksaa yhteensä 2 krediittiä, myös tuntemattomien tulosten kanssa; yksi HTTP-pyyntö ei tarkoita yhtä ennustekrediittiä.

Tarkista jokainen kohde, vaikka erä palauttaisi HTTP 200 -vastauksen. Tallenna onnistuneet ja tuntemattomat tulokset ja tarkista sitten virheet ja vahvistettu laskutus ennen kuin lähetät epäonnistuneet kohteet uudelleen. Älä lähetä koko onnistunutta erää uudelleen aikakatkaisun jälkeen tarkistamatta laskutuksen tulosta.

- [Eräpyyntöjen esimerkit, rajat ja osittaiset virheet](https://www.genderapi.io/fi/docs/v2/batch)

## Tiedä, mitä lähetät

Reaaliaikainen demo lähettää syöttämäsi arvon GenderAPI.io-palveluun vain, kun lähetät sen itse. Jos tekoälyä käytetään, lähetetyt type, value ja maakonteksti välitetään ennusteisiin määritetylle palvelulle. Jos haluat ennusteen pelkästä tietoaineistosta, käytä integraatiossasi asetusta options.ai_mode: off ilman forceToGenderize-asetusta.

Tietosuojakäytäntö, tietojenkäsittelysopimus ja alikäsittelijäluettelo kuvaavat julkaistut käsittelyehdot. Tulos on päätelty yhteys; anna henkilön itse ilmoittamien tietojen mennä sen edelle. Älä käytä tulosta perusteena yksilöä koskeville merkittäville päätöksille.

- [Tietosuojakäytäntö](https://www.genderapi.io/fi/privacy-policy)
- [Tietojenkäsittelysopimus](https://www.genderapi.io/fi/data-processing-agreement)
- [Alikäsittelijäluettelo](https://www.genderapi.io/fi/subprocessors)

## Voiko API poimia etunimen sähköpostiosoitteesta?

Se voi palauttaa nimiehdokkaan, kun paikallisessa osassa on käyttökelpoinen signaali. Osuma voi perustua kokonaisiin osiin tai merkkijonon osiin, joten tarkista data.match. Tulos ei todista postilaatikon omistajan etunimeä.

## Palauttavatko osoitteet kuten info@ tai support@ sukupuolen?

Jaetut rooliosoitteet eivät yleensä sisällä perusteita henkilönnimelle. Tuntematon tulos on kelvollinen. Tekoälyä tai lempinimitilaa ei pidä pitää jaettua postilaatikkoa käyttävien henkilöiden vahvistuksena.

## Kuluttaako tuntematon sähköpostitulos krediittejä?

Kyllä. Onnistunut tavallinen sähköpostihaku maksaa 1 krediitin, myös tekoäly varalla ja tuntemattomat tulokset. Pakotettu lempinimipäättely maksaa 1 krediitin tietoaineistosta ratkaistusta tuloksesta tai yhteensä 2, jos tekoälyä käytetään. Virheiden laskutustulos ilmoitetaan erikseen kentässä meta.usage.

## Poistetaanko sähköpostin verkkotunnus ennen tekoälykäsittelyä?

Tällaista poistoa ei luvata. Tietoaineiston ehdokkaat muodostetaan paikallisesta osasta, kun taas tekoäly saa lähetetyn arvon ja ohjeen jättää verkkotunnus ja plus-merkin jälkeinen pääte huomiotta. Käytä pelkän tietoaineiston tilaa, jos työnkulkusi sitä edellyttää.