oneapi
Autentificare
Utile v1 / Email

Verifică o adresă de email

Semnale despre o adresă de email: forma e corectă, domeniul are MX, e un furnizor de adrese temporare, e un alias cu plus. Nu trimite niciun mesaj de verificare.

POST
https://oneapi.ro/api/utile/v1/email/valideaza

Corpul cererii

Se trimite ca JSON, în corpul cererii (Content-Type: application/json) — nu în şirul de interogare.

NumeTipDescriereValori acceptate
adresaobligatoriu string OBLIGATORIU. Adresa de verificat, cel mult 320 de caractere. max 320 car.
mxopțional boolean | null 0 sare peste interogarea DNS și verifică doar sintaxa. Implicit se verifică.
Adresă obișnuită Corpul cererii 
{
    "adresa": "ion.popescu@example.com"
}
Domeniu temporar Corpul cererii 
{
    "adresa": "test@mailinator.com"
}
Doar sintaxa, fără DNS Corpul cererii 
{
    "adresa": "ion@exemplu.ro",
    "mx": false
}

Parametri de interogare

Ruta nu acceptă parametri de interogare.

Cum se comportă

  • POST, cu adresa în corp (JSON): adresa (obligatoriu, cel mult 320 de caractere) și mx (false sare peste interogarea DNS și verifică doar sintaxa; implicit se verifică). O adresă de e-mail e dată personală: într-un URL ar ajunge în logurile de acces și în referrer — de aceea un GET primește 405 metoda_nepotrivita.
  • Nu e un verdict. Singura verificare care dovedește că o adresă există e trimiterea unui mesaj cu link de confirmare. Tot ce dă ruta asta sunt SEMNALE — o adresă poate trece toate verificările și să nu existe, iar una respinsă de listă poate fi perfect funcțională.
  • Adresa NU se validează la poartă cu regula obișnuită de email, deliberat: exact asta e ce trebuie să raporteze ruta. Respinsă la intrare, o adresă stricată n-ar mai ajunge niciodată la analiză.
  • Lipsa înregistrărilor MX nu înseamnă automat că domeniul nu primește mail. RFC 5321 spune că un domeniu fără MX, dar cu A sau AAAA, e destinatar valid — de aceea stare distinge fara_mx_dar_cu_a de fara_mx_si_fara_a.
  • Domeniile internaționalizate sunt convertite la Punycode înainte de orice verificare, fiindcă și filtrul de sintaxă, și DNS-ul lucrează pe forma ASCII. domeniu din răspuns e forma convertită.
  • Interogarea DNS are ritm pe două niveluri (per utilizator și global) și cache de 10 minute pe DOMENIU. Când ritmul e depășit sau serverul DNS nu răspunde, mx.verificat e false cu motivul, iar poate_primi_mail e null — o pană DNS nu se transformă în „domeniul nu primește mail” și nu intră în cache. Interogarea are timeout de 2 secunde, o singură încercare, iar după 5 pene la rând verificarea MX se oprește 2 minute (motivul o spune) — o cerere nu mai stă 10 secunde pe un DNS căzut.
  • Zero retenție: adresa nu se scrie nicăieri, nici în loguri, nici în bază. Singurul lucru care ajunge în cache e răspunsul DNS pentru domeniu, care nu spune nimic despre persoana din fața lui @.

La ce folosește

  • Prinzi greșelile de tastare la înregistrare, înainte ca mailul de confirmare să se piardă.
  • Filtrezi adresele de unică folosință dintr-un formular de înscriere la newsletter.
  • Separi cutiile de rol (office@) de adresele nominale, într-o bază de contacte.

Structura răspunsului

Toate câmpurile de mai jos sunt în data.

CâmpTipDescriere
adresa string Adresa, în forma publicată de sursă.
normalizata string Adresa cu partea locală în litere mici și domeniul în formă ASCII.
local string Partea dinaintea lui @.
domeniu string Domeniul, în formă ASCII (Punycode dacă era internaționalizat).
eticheta null Sufixul +etichetă, pe care unii furnizori îl ignoră la livrare. Util la deduplicare.
semnale.sintaxa_valida boolean Dacă adresa trece RFC 5322 și limitele de lungime.
semnale.domeniu_temporar boolean Dacă domeniul e pe lista celor de unică folosință.
semnale.cutie_de_rol boolean Dacă e o cutie de funcție (office@, info@), nu a unei persoane.
semnale.poate_primi_mail boolean Dacă domeniul are MX sau A. null dacă verificarea n-a fost făcută.
probleme array Ce anume nu e în regulă la sintaxă, în cuvinte.
mx.verificat boolean Dacă interogarea DNS chiar a dat un răspuns. La false, mx.motiv spune de ce (ritm depășit ori server DNS care n-a răspuns).
mx.stare string are_mx, fara_mx_dar_cu_a sau fara_mx_si_fara_a; lipsește la verificat: false.
mx.poate_primi boolean
mx.servere[] array Serverele de mail, ordonate după prioritate.
mx.servere[].server string
mx.servere[].prioritate integer
scor integer Un 0–100 compus din semnalele de mai sus, pentru cine vrea o singură cifră. E derivat, nu o măsurătoare.
observatie string Precizare despre cum se citeşte răspunsul: o convenţie de calcul sau o limită a datelor.
sursa.domenii_temporare string
sursa.mx string
sursa.sintaxa string
mx.motiv De ce n-a existat verificare; apare doar la verificat: false.

Exemple de răspuns

corp: {"adresa": "ion.popescu@example.com"}

POSThttps://oneapi.ro/api/utile/v1/email/valideaza
{
    "data": {
        "adresa": "ion.popescu@example.com",
        "normalizata": "ion.popescu@example.com",
        "local": "ion.popescu",
        "domeniu": "example.com",
        "eticheta": null,
        "semnale": {
            "sintaxa_valida": true,
            "domeniu_temporar": false,
            "cutie_de_rol": false,
            "poate_primi_mail": true
        },
        "probleme": [],
        "mx": {
            "verificat": true,
            "stare": "are_mx",
            "poate_primi": true,
            "servere": [
                {
                    "server": "",
                    "prioritate": 0
                }
            ]
        },
        "scor": 90,
        "observatie": "Semnalele NU sunt un verdict. O adresă poate trece toate verificările și să nu existe; una respinsă de listă poate fi perfect funcțională. Singura dovadă că o adresă e reală e un mesaj de confirmare livrat.",
        "sursa": {
            "domenii_temporare": "disposable-email-domains — CC0 1.0",
            "mx": "interogare DNS live, cu cache de o oră pe domeniu",
            "sintaxa": "RFC 5322 (prin filtrul PHP) plus limitele de lungime din RFC 5321"
        }
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
405eroaremetoda_nepotrivita: ruta primește doar POST, cu adresa în corp.
422validareadresa lipsește sau depășește 320 de caractere.
429cota_depasitaCota lunară a planului a fost depăşită (vezi Retry-After).

Toate erorile au aceeași formă. eroare.cod e stabil și e cel după care trebuie să ramifici în cod — nu după textul din mesaj, care se poate schimba.

{
    "eroare": {
        "cod": "validare",
        "mesaj": "adresa lipsește sau depășește 320 de caractere."
    }
}