Verifica Email API: convalida del codice OTP

curl

curl -X POST https://verification.didit.me/v3/email/check/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "alice@example.com",
    "code": "123456",
    "disposable_email_action": "DECLINE"
  }'

import Didit from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.email.checkCode({
  email: "alice@example.com",
  code: "123456",
});
console.log(result);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Email.CheckCode(ctx, didit.EmailCheckCodeParams{
	Email: "alice@example.com",
	Code:  "123456",
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.EmailCheckCodeParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.email().checkCode(EmailCheckCodeParams.builder()
        .email("alice@example.com")
        .code("123456")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->email->checkCode([
    'email' => 'alice@example.com',
    'code' => '123456',
]);
print_r($result->toArray());

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.Email.CheckCodeAsync(new EmailCheckCodeParams
{
    Email = "alice@example.com",
    Code = "123456",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24",
  "status": "Approved",
  "message": "The verification code is correct.",
  "email": {
    "status": "Approved",
    "email": "alice@example.com",
    "is_breached": false,
    "breaches": [],
    "is_disposable": false,
    "is_undeliverable": false,
    "verification_attempts": 1,
    "verified_at": "2026-06-12T01:24:47.311323Z",
    "warnings": [],
    "lifecycle": [
      {
        "type": "EMAIL_VERIFICATION_MESSAGE_SENT",
        "timestamp": "2026-06-12T01:23:39.580554+00:00",
        "details": {
          "status": "Success",
          "reason": null
        },
        "fee": 0.02
      },
      {
        "type": "VALID_CODE_ENTERED",
        "timestamp": "2026-06-12T01:24:47.311201+00:00",
        "details": {
          "code_tried": "123456",
          "status": "Approved"
        },
        "fee": 0
      },
      {
        "type": "EMAIL_VERIFICATION_APPROVED",
        "timestamp": "2026-06-12T01:24:47.384292+00:00",
        "details": null,
        "fee": 0
      }
    ],
    "matches": []
  },
  "vendor_data": "user-1234",
  "metadata": null,
  "created_at": "2026-06-12T01:24:47.401719+00:00"
}

POST

check

curl

curl -X POST https://verification.didit.me/v3/email/check/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "alice@example.com",
    "code": "123456",
    "disposable_email_action": "DECLINE"
  }'

import Didit from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.email.checkCode({
  email: "alice@example.com",
  code: "123456",
});
console.log(result);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Email.CheckCode(ctx, didit.EmailCheckCodeParams{
	Email: "alice@example.com",
	Code:  "123456",
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.EmailCheckCodeParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.email().checkCode(EmailCheckCodeParams.builder()
        .email("alice@example.com")
        .code("123456")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->email->checkCode([
    'email' => 'alice@example.com',
    'code' => '123456',
]);
print_r($result->toArray());

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.Email.CheckCodeAsync(new EmailCheckCodeParams
{
    Email = "alice@example.com",
    Code = "123456",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24",
  "status": "Approved",
  "message": "The verification code is correct.",
  "email": {
    "status": "Approved",
    "email": "alice@example.com",
    "is_breached": false,
    "breaches": [],
    "is_disposable": false,
    "is_undeliverable": false,
    "verification_attempts": 1,
    "verified_at": "2026-06-12T01:24:47.311323Z",
    "warnings": [],
    "lifecycle": [
      {
        "type": "EMAIL_VERIFICATION_MESSAGE_SENT",
        "timestamp": "2026-06-12T01:23:39.580554+00:00",
        "details": {
          "status": "Success",
          "reason": null
        },
        "fee": 0.02
      },
      {
        "type": "VALID_CODE_ENTERED",
        "timestamp": "2026-06-12T01:24:47.311201+00:00",
        "details": {
          "code_tried": "123456",
          "status": "Approved"
        },
        "fee": 0
      },
      {
        "type": "EMAIL_VERIFICATION_APPROVED",
        "timestamp": "2026-06-12T01:24:47.384292+00:00",
        "details": null,
        "fee": 0
      }
    ],
    "matches": []
  },
  "vendor_data": "user-1234",
  "metadata": null,
  "created_at": "2026-06-12T01:24:47.401719+00:00"
}

Componente aggiuntivo di intelligence

Imposta enable_enrichment su true per eseguire anche l’analisi dell’indirizzo email tramite intelligence: un punteggio di rischio e la sua cronologia di violazioni dei dati. Il componente aggiuntivo viene fatturato $0.05 per richiesta al prezzo di listino, in aggiunta al prezzo del controllo. La richiesta restituisce 403 quando il tuo saldo non è sufficiente a coprire il costo. Tre campi determinano l’effetto dei segnali. Ciascuno può essere NO_ACTION (valore predefinito) o DECLINE, e ognuno ha effetto solo quando enable_enrichment è true.

Campo	Rifiuta quando
`email_intelligence_score_action`	Il punteggio di rischio supera la soglia.
`recent_email_breach_action`	L’indirizzo compare in una violazione dei dati recente e nota.
`frequent_email_breach_action`	L’indirizzo compare in molte violazioni dei dati note.

Con NO_ACTION, il segnale viene comunque restituito in email.email_intelligence, così puoi applicare una tua regola.

Autorizzazioni

x-api-key

string

header

obbligatorio

La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys.

Corpo

application/json

string<email>

obbligatorio

Lo stesso indirizzo email utilizzato nella chiamata corrispondente POST /v3/email/send/. Questo è ciò che collega la verifica all'invio.

Esempio:

"alice@example.com"

code

string

obbligatorio

L'OTP ricevuto dall'utente finale: 4–8 cifre, oppure 4–8 lettere/cifre quando è stato utilizzato alphanumeric_code: true al momento dell'invio. Il confronto non fa distinzione tra maiuscole e minuscole.

Maximum string length: 10

Esempio:

"123456"

duplicated_email_action

enum<string>

predefinito:NO_ACTION

Cosa fare quando lo stesso indirizzo è già stato utilizzato e approvato da un utente diverso (contano solo le verifiche precedentemente approvate) (diverso vendor_data) della tua applicazione. DECLINE imposta lo status finale su Declined; NO_ACTION registra il rischio in email.warnings e popola email.matches.

Opzioni disponibili:

NO_ACTION,

DECLINE

breached_email_action

enum<string>

predefinito:NO_ACTION

Cosa fare quando l'indirizzo compare in violazioni di dati note (email.is_breached). DECLINE imposta lo status finale su Declined; NO_ACTION registra il rischio in email.warnings.

Opzioni disponibili:

NO_ACTION,

DECLINE

disposable_email_action

enum<string>

predefinito:NO_ACTION

Cosa fare quando il dominio appartiene a un provider di posta usa e getta/temporanea (email.is_disposable). DECLINE imposta lo status finale su Declined; NO_ACTION registra il rischio in email.warnings.

Opzioni disponibili:

NO_ACTION,

DECLINE

enable_enrichment

boolean

predefinito:false

Quando è true, esegue anche l'analisi dell'indirizzo email: un punteggio di rischio e la relativa cronologia delle violazioni. Fatturato come un'unità email_intelligence_api per richiesta ($0.05 a prezzo di listino) in aggiunta al prezzo di questo endpoint. La richiesta restituisce 403 quando il tuo saldo non è sufficiente a coprirlo.

Esempio:

false

email_intelligence_score_action

enum<string>

predefinito:NO_ACTION

Azione quando il punteggio di rischio dell'intelligence delle email supera la soglia. DECLINE imposta lo status finale su Declined; NO_ACTION registra il segnale senza rifiutare. Ha effetto solo quando enable_enrichment è true.

Opzioni disponibili:

NO_ACTION,

DECLINE

recent_email_breach_action

enum<string>

predefinito:NO_ACTION

Azione quando l'indirizzo compare in una recente violazione dei dati nota. DECLINE imposta lo status finale su Declined; NO_ACTION registra il segnale senza rifiutare. Ha effetto solo quando enable_enrichment è true.

Opzioni disponibili:

NO_ACTION,

DECLINE

frequent_email_breach_action

enum<string>

predefinito:NO_ACTION

Azione quando l'indirizzo compare in molteplici violazioni dei dati note. DECLINE imposta lo status finale su Declined; NO_ACTION registra il segnale senza rifiutare. Ha effetto solo quando enable_enrichment è true.

Opzioni disponibili:

NO_ACTION,

DECLINE

Se true, cerca anche l'impronta social dell'indirizzo: le piattaforme email, social, professionali, di e-commerce e di intrattenimento su cui è registrato. Fatturato come un'unità email_social per richiesta in aggiunta al prezzo di questo endpoint.

Esempio:

true

Azione quando il controllo dell'impronta social rileva che l'indirizzo non è registrato su nessuna delle piattaforme coperte. Solo NO_ACTION e DECLINE sono accettati su questo endpoint; REVIEW è disponibile sulla chiave di configurazione del workflow con lo stesso nome.

Opzioni disponibili:

NO_ACTION,

DECLINE

Risposta

Verifica completata: anche i codici errati e le verifiche mancanti restituiscono 200; esamina status, non il codice HTTP. Il campo email viene popolato solo per gli esiti definitivi (Approved/Declined), è null per Failed ed è assente per Expired or Not Found.

request_id

string<uuid>

Su Approved/Declined: l'id di sessione della verifica corrispondente — identico al request_id restituito da POST /v3/email/send/. Su Failed ed Expired or Not Found: un UUID casuale monouso che non può essere cercato in seguito.

status

enum<string>

Approved — codice corretto, nessun rischio di rifiuto. Declined — definitivo: è stato rilevato un rischio che comporta il rifiuto oppure il limite di tentativi (3) è stato esaurito. Failed — codice errato, tentativi rimanenti. Expired or Not Found — nessuna verifica in attesa per questo indirizzo negli ultimi 5 minuti.

Opzioni disponibili:

Approved,

Declined,

Failed,

Expired or Not Found

message

string

Spiegazione di facile lettura dell'esito, compreso il numero di tentativi rimanenti dopo un codice errato.

object | null

Report email completo. Presente (non nullo) solo per gli esiti finalizzati (Approved/Declined); null su Failed e assente su Expired or Not Found.

Show child attributes

vendor_data

string | null

vendor_data della sessione della verifica corrispondente. null in caso di Expired or Not Found.

metadata

object | null

metadata della sessione di verifica corrispondente. null in caso di Expired or Not Found.

created_at

string<date-time>

Timestamp della risposta a questo controllo.

Ultima modifica il 7 novembre 2026

​Componente aggiuntivo di intelligence

Autorizzazioni

Corpo

Risposta

Componente aggiuntivo di intelligence