> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Verifica email: API per inviare il codice monouso > Didit: POST /v3/email/send/ invia un codice monouso di verifica. Nuovo tentativo automatico, validità 5-min, a consumo, nessun minimo mensile. ## OpenAPI ````yaml it/openapi-25.json POST /v3/email/send/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API di verifica dell'identità. Autenticati con l'intestazione x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/email/send/: post: tags: - Standalone APIs summary: Invia codice email description: >- Invia un codice monouso (OTP) a un indirizzo email, quindi verificalo con [`POST /v3/email/check/`](/it/standalone-apis/email-check). **Come si abbinano invio e verifica.** Lo stato della verifica è associato alla tua applicazione e all'indirizzo `email` — la chiamata di verifica non richiede `request_id`. Ogni nuovo invio crea una verifica in sospeso valida per **5 minuti**: chiama l'endpoint di verifica con lo stesso indirizzo e il codice ricevuto dall'utente prima che la finestra temporale scada. Se chiami nuovamente l'invio per lo stesso indirizzo mentre una verifica è ancora in sospeso, viene generato un nuovo codice per quella stessa verifica (`status: "Retry"`, stesso `request_id`); il codice precedente smette di funzionare. È possibile associare al massimo un nuovo tentativo in questo modo (due invii in totale); un ulteriore invio avvia una nuova verifica con un nuovo `request_id`. La finestra di 5 minuti viene calcolata a partire dal primo invio e non viene prolungata dai nuovi tentativi. **Pre-verifica di recapitabilità.** Prima di qualsiasi invio, l'indirizzo viene sottoposto a una validazione della sintassi e dei record DNS/MX. Gli indirizzi non in grado di ricevere posta restituiscono `200` con `status: "Undeliverable"` e `reason: "email_can_not_be_delivered"` — non viene inviata alcuna email, non viene addebitato alcun costo e la verifica viene immediatamente finalizzata come `Declined` (un controllo successivo restituisce `Expired or Not Found`). Un invio che fallisce per un motivo non legato all'indirizzo (l'email non ha potuto essere presa in carico per la consegna) restituisce invece `503`: nessun codice viene inviato, non viene addebitato alcun costo, la verifica rimane aperta e la stessa richiesta può essere ripetuta. **Formato del codice e personalizzazione del brand.** I codici sono composti da 4–8 caratteri (`options.code_size`, predefinito 6), numerici per impostazione predefinita; imposta `options.alphanumeric_code: true` per lettere maiuscole e cifre (il confronto in fase di verifica non fa distinzione tra maiuscole e minuscole). Il modello email è localizzato tramite `options.locale` (54 lingue supportate) e può utilizzare la personalizzazione del brand white label della tua applicazione tramite `options.use_white_label_customization`. **Fatturazione.** Un credito API di Email Verification per ogni invio riuscito (`status: "Success"`), addebitato al momento dell'invio. Gli invii con esito `Retry` e `Undeliverable` sono gratuiti, così come le verifiche. **Persistenza della sessione.** Ogni nuova verifica viene salvata come sessione di tipo API: `request_id` è un vero ID sessione che puoi passare a `GET /v3/session/{sessionId}/decision/`, la verifica compare nella Business Console e i webhook `status.updated` vengono attivati man mano che procede. **Sandbox.** Le chiavi API sandbox ignorano la consegna e la fatturazione: dopo la validazione della richiesta (l'input non valido restituisce comunque `400`), l'endpoint restituisce un payload statico `Success` con un `request_id` casuale; non viene inviata alcuna email e nulla viene memorizzato. Usa il codice `123456` per il controllo in sandbox. **Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{"detail": "You do not have permission to perform this action."}`) — questa API non restituisce mai `401`. **Limite di frequenza.** Budget di scrittura condiviso di 300 richieste/min per chiave API su tutti gli endpoint POST/PATCH/DELETE; il superamento restituisce `429`. operationId: post_v3email_send requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email description: >- Indirizzo email del destinatario. Gli indirizzi non formattati correttamente restituiscono `400`; gli indirizzi sintatticamente validi che non possono ricevere posta (convalida DNS/MX non riuscita) restituiscono `200` con `status: "Undeliverable"`. example: alice@example.com options: type: object description: >- Opzioni di formato, localizzazione e branding dell'OTP. Tutti i campi sono facoltativi. properties: code_size: type: integer minimum: 4 maximum: 8 default: 6 description: >- Numero di caratteri nell'OTP (cifre per impostazione predefinita; lettere maiuscole e cifre quando `alphanumeric_code` è `true`). alphanumeric_code: type: boolean default: false description: >- Quando è `true`, l'OTP è composto da lettere maiuscole `A–Z` e cifre `0–9` anziché solo da cifre. Il confronto in `/v3/email/check/` non fa distinzione tra maiuscole e minuscole. locale: type: string maxLength: 5 enum: - en - ar - bn - bg - bs - ca - cs - da - de - el - es - et - fa - fi - fr - he - hi - hr - hu - hy - id - it - ja - ka - kk - ko - ky - lt - lv - cnr - mk - mn - ms - nl - 'no' - pl - pt-BR - pt - ro - ru - sk - sl - so - sq - sr - sv - th - tr - uk - uz - vi - zh-CN - zh-TW - zh description: >- Lingua del modello di email OTP. Il valore predefinito è `en`. I valori non supportati restituiscono `400` elencando tutte le impostazioni locali supportate. example: en use_white_label_customization: type: boolean default: false description: >- Quando è `true`, l'email con l'OTP utilizza la personalizzazione white label della tua applicazione (logo, colori, personalizzazione del mittente) anziché il modello predefinito di Didit. signals: type: object description: >- Segnali opzionali di dispositivo e rete relativi all'utente finale, inoltrati al livello antifrode per migliorare il rilevamento del traffico abusivo o automatizzato. Tutti i campi sono opzionali. properties: ip: type: string description: >- Indirizzo IP del dispositivo dell'utente finale. IPv4 o IPv6. example: 192.0.2.1 device_id: type: string maxLength: 255 description: >- Identificativo univoco del dispositivo dell'utente finale. Android: `ANDROID_ID`; iOS: `identifierForVendor`. example: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: type: string enum: - android - ios - ipados - tvos - web description: Piattaforma del dispositivo dell'utente finale. device_model: type: string maxLength: 255 description: Modello del dispositivo dell'utente finale. example: iPhone17,2 os_version: type: string maxLength: 64 description: >- Versione del sistema operativo del dispositivo dell'utente finale. example: 18.0.1 app_version: type: string maxLength: 64 description: Versione della tua applicazione. example: 1.2.34 user_agent: type: string maxLength: 512 description: User agent del browser o dell'app dell'utente finale. example: >- Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1 vendor_data: type: string description: >- Identificatore opzionale controllato dal chiamante (il tuo ID utente interno, un'email, un UUID, ecc.) memorizzato nella sessione e restituito nella risposta di invio, nella risposta di verifica della corrispondenza, nei webhook e nella Business Console. Usalo per correlare il `request_id` di Didit con il record del tuo utente. metadata: type: object nullable: true description: >- Oggetto JSON a struttura libera opzionale memorizzato nella sessione e restituito nella risposta di invio, nella risposta del controllo di corrispondenza, nei webhook e nella Business Console. required: - email examples: Numeric 6-digit code: summary: Predefinito — codice numerico a 6 cifre in inglese value: email: alice@example.com options: locale: en vendor_data: user-1234 Alphanumeric 8-character code: summary: Lettere maiuscole + cifre, modello spagnolo value: email: bob@example.com options: code_size: 8 alphanumeric_code: true locale: es White-label branding: summary: >- Invia l'email OTP con la personalizzazione white label della tua applicazione value: email: carol@example.com options: locale: en use_white_label_customization: true vendor_data: user-5678 responses: '200': description: >- Invio confermato. Ispeziona `status`: `Success` e `Retry` indicano che un codice è in arrivo; `Undeliverable` indica che l'indirizzo non può ricevere posta e la verifica è già finalizzata come `Declined`. `request_id` è l'ID di sessione persistente (stesso ID in caso di `Retry`). content: application/json: schema: $ref: '#/components/schemas/EmailVerificationSendResponse' examples: Success: summary: OTP inviato via email per una nuova verifica (fatturato) value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Success reason: null vendor_data: user-1234 metadata: null Retry: summary: >- Secondo invio entro la finestra di 5 minuti — nuovo codice, stesso request_id, gratuito value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Retry reason: null vendor_data: user-1234 metadata: null Undeliverable: summary: >- L'indirizzo non ha superato la convalida DNS/MX: verifica completata come Rifiutata, nessun addebito value: request_id: cb1a5011-344d-444d-bdce-218904745d7f status: Undeliverable reason: email_can_not_be_delivered vendor_data: user-1234 metadata: null '400': description: >- Errore di validazione — busta dell'errore di campo di DRF: un array di messaggi per campo non conforme, annidato sotto `options` per gli errori delle opzioni. content: application/json: examples: Invalid email: summary: Indirizzo email non valido value: email: - Enter a valid email address. Unsupported locale: summary: '`options.locale` non compreso tra quelli supportati' value: options: locale: - >- Invalid locale. Supported locales are en, ar, bn, bg, bs, ca, cs, da, de, el, es, et, fa, fi, fr, he, hi, hr, hu, hy, id, it, ja, ka, kk, ko, ky, lt, lv, cnr, mk, mn, ms, nl, no, pl, pt-BR, pt, ro, ru, sk, sl, so, sq, sr, sv, th, tr, uk, uz, vi, zh-CN, zh-TW, zh. Code size out of range: summary: '`options.code_size` non compreso tra 4 e 8' value: options: code_size: - Ensure this value is less than or equal to 8. '403': description: >- Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante (`{"detail": ...}`); una chiave errata, revocata o scaduta restituisce `401`. Restituito inoltre prima di qualsiasi invio quando il saldo dell'organizzazione non è sufficiente a coprire un credito dell'API Verifica email (`{"error": ...}`). content: application/json: examples: Missing or invalid API key: summary: >- Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata value: detail: You do not have permission to perform this action. Not enough credits: summary: >- Il saldo dell'organizzazione non è sufficiente per coprire il prezzo di invio value: error: You don't have enough credits to perform this request. '429': description: >- Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Più di 300 richieste di scrittura nel minuto corrente value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '503': description: >- Impossibile inviare l'email per un motivo indipendente dall'indirizzo (il provider email non è raggiungibile, è andato in timeout o ha rifiutato l'invio stesso), quindi nessun codice è stato inviato e nulla è stato fatturato o conteggiato come tentativo di invio. Ripeti la stessa richiesta. content: application/json: examples: Email delivery unavailable: summary: >- Il provider email non è riuscito a inviare l'email dopo un nuovo tentativo automatico value: detail: >- Email delivery is temporarily unavailable. Please try again. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/email/send/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "email": "alice@example.com", "options": { "code_size": 6, "locale": "en" }, "vendor_data": "user-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.email.send_code( email="alice@example.com", options={ "locale": "en", }, vendor_data="user-1234", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.email.sendCode({ email: "alice@example.com", options: { locale: "en", }, vendor_data: "user-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Email.SendCode(ctx, didit.EmailSendCodeParams{\n\tEmail: \"alice@example.com\",\n\tOptions: didit.Some(didit.EmailSendCodeParamsOptions{\n\t\tLocale: didit.Some(didit.EmailSendCodeParamsOptionsLocale(\"en\")),\n\t}),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: |- import me.didit.Didit; import me.didit.types.EmailSendCodeParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.email().sendCode(EmailSendCodeParams.builder() .email("alice@example.com") .options(EmailSendCodeParams.Options.builder() .locale(EmailSendCodeParams.Options.Locale.of("en")) .build()) .vendorData("user-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- email->sendCode([ 'email' => 'alice@example.com', 'options' => [ 'locale' => 'en', ], 'vendor_data' => 'user-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.email.send_code( email: "alice@example.com", options: { locale: "en", }, vendor_data: "user-1234" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Email.SendCodeAsync(new EmailSendCodeParams { Email = "alice@example.com", Options = new EmailSendCodeParamsOptions { Locale = new EmailSendCodeParamsOptionsLocale("en"), }, VendorData = "user-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: EmailVerificationSendResponse: type: object properties: request_id: type: string format: uuid description: >- ID sessione della verifica. Un invio `Retry` restituisce lo stesso `request_id` dell'invio originale. Questo id compare nella Business Console, viene restituito nuovamente da un `POST /v3/email/check/` finalizzato e può essere passato a `GET /v3/session/{sessionId}/decision/`. status: type: string enum: - Success - Retry - Undeliverable description: >- `Success` — OTP inviato via email per una nuova verifica (fatturata). `Retry` — nuovo OTP inviato via email per la verifica in sospeso creata da un invio precedente (gratuito). `Undeliverable` — l'indirizzo non ha superato la convalida di recapito o non è stato possibile inviare il messaggio; la verifica viene immediatamente finalizzata come `Declined` e non viene addebitato nulla. reason: type: string nullable: true enum: - email_can_not_be_delivered - null description: >- `email_can_not_be_delivered` quando `status` è `Undeliverable`; `null` altrimenti. vendor_data: type: string nullable: true description: Eco del `vendor_data` memorizzato nella sessione (dal primo invio). metadata: type: object nullable: true description: Eco dei `metadata` memorizzati nella sessione (dal primo invio). securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.