> ## 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. # API per enviar codi de verificació per correu electrònic > Envia un codi d'un sol ús per correu amb Didit. POST /v3/email/send/. Reintent automàtic, validesa de 5 min, preu per ús, sense mínims mensuals. ## OpenAPI ````yaml ca/openapi-25.json POST /v3/email/send/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/email/send/: post: tags: - Standalone APIs summary: Enviar el codi per correu electrònic description: >- Envia un codi d'un sol ús (OTP) a una adreça de correu electrònic i, després, verifica'l amb [`POST /v3/email/check/`](/ca/standalone-apis/email-check). **Com s'associen l'enviament i la comprovació.** L'estat de verificació s'identifica mitjançant la teva aplicació juntament amb l'adreça `email`; la crida de comprovació no admet `request_id`. Cada nou enviament crea una verificació pendent que dura **5 minuts**: crida la comprovació amb la mateixa adreça i el codi que ha rebut l'usuari abans que es tanqui la finestra. Si tornes a cridar l'enviament per a la mateixa adreça mentre hi ha una verificació pendent, es genera un nou codi per a aquesta mateixa verificació (`status: "Retry"`, mateix `request_id`); el codi anterior deixa de funcionar. Com a màxim s'associa un reintent d'aquesta manera (dos enviaments en total); un enviament posterior inicia una nova verificació amb un nou `request_id`. La finestra de 5 minuts es compta a partir del primer enviament i els reintents no l'amplien. **Comprovació prèvia de lliurabilitat.** Abans d'enviar res, l'adreça passa per una validació de sintaxi i de DNS/MX. Les adreces que no poden rebre correu retornen `200` amb `status: "Undeliverable"` i `reason: "email_can_not_be_delivered"`: no s'envia cap correu electrònic, no es factura res i la verificació es finalitza immediatament com a `Declined` (una comprovació posterior retorna `Expired or Not Found`). Un enviament que falla per un motiu que no és l'adreça (el correu electrònic no s'ha pogut lliurar per enviar-lo) retorna `503`: no s'envia cap codi, no es factura res, la verificació roman oberta i es pot repetir la mateixa sol·licitud. **Format del codi i personalització de marca.** Els codis tenen entre 4 i 8 caràcters (`options.code_size`, per defecte 6), numèrics per defecte; defineix `options.alphanumeric_code: true` per a lletres majúscules i dígits (la comparació que es fa en la comprovació no distingeix entre majúscules i minúscules). La plantilla de correu electrònic es localitza mitjançant `options.locale` (54 idiomes admesos) i pot utilitzar la personalització de marca blanca de la teva aplicació mitjançant `options.use_white_label_customization`. **Facturació.** Un crèdit de l'API de Verificació de correu electrònic per enviament satisfactori (`status: "Success"`), cobrat en el moment de l'enviament. Els enviaments `Retry` i `Undeliverable` són gratuïts, i les comprovacions són gratuïtes. **Persistència de la sessió.** Cada nova verificació es manté com una sessió de tipus API: `request_id` és un id de sessió real que pots passar a `GET /v3/session/{sessionId}/decision/`, la verificació apareix a la Business Console i els webhooks `status.updated` s'activen a mesura que avança. **Sandbox.** Les claus d'API de sandbox ometen el lliurament i la facturació: després de la validació de la sol·licitud (l'entrada amb format incorrecte continua retornant `400`), l'endpoint retorna un payload estàtic `Success` amb un `request_id` aleatori; no s'envia cap correu electrònic i no es desa res de manera persistent. Utilitza el codi `123456` a la comprovació de sandbox. **Autenticació.** Envia la clau d'API de la teva aplicació a la capçalera `x-api-key`. Les credencials absents o no vàlides retornen `403` (`{"detail": "You do not have permission to perform this action."}`); aquesta API mai retorna `401`. **Límit de freqüència.** Límit d'escriptura compartit de 300 sol·licituds/min per clau d'API en tots els endpoints POST/PATCH/DELETE; superar-lo retorna `429`. operationId: post_v3email_send requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email description: >- Adreça de correu electrònic del destinatari. Les adreces amb un format incorrecte retornen `400`; les adreces sintàcticament vàlides que no poden rebre correu (error de validació de DNS/MX) retornen `200` amb `status: "Undeliverable"`. example: alice@example.com options: type: object description: >- Opcions de format, localització i personalització de marca de l'OTP. Tots els camps són opcionals. properties: code_size: type: integer minimum: 4 maximum: 8 default: 6 description: >- Nombre de caràcters de l'OTP (dígits per defecte; lletres majúscules i dígits quan `alphanumeric_code` és `true`). alphanumeric_code: type: boolean default: false description: >- Quan és `true`, l'OTP està compost per lletres majúscules `A–Z` i dígits `0–9` en lloc de només dígits. La comparació a `/v3/email/check/` no distingeix entre majúscules i minúscules. 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: >- Idioma de la plantilla de correu electrònic d'OTP. Per defecte és `en`. Els valors no admesos retornen `400` amb una llista de tots els idiomes admesos. example: en use_white_label_customization: type: boolean default: false description: >- Quan és `true`, el correu electrònic amb l'OTP utilitza la personalització de marca blanca de la teva aplicació (logotip, colors, marca del remitent) en lloc de la plantilla per defecte de Didit. signals: type: object description: >- Senyals opcionals de dispositiu i xarxa sobre l'usuari final, reenviats a la capa antifrau per millorar la detecció de trànsit abusiu o automatitzat. Tots els camps són opcionals. properties: ip: type: string description: Adreça IP del dispositiu de l'usuari final. IPv4 o IPv6. example: 192.0.2.1 device_id: type: string maxLength: 255 description: >- Identificador únic del dispositiu de l'usuari final. Android: `ANDROID_ID`; iOS: `identifierForVendor`. example: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: type: string enum: - android - ios - ipados - tvos - web description: Plataforma del dispositiu de l'usuari final. device_model: type: string maxLength: 255 description: Model del dispositiu de l'usuari final. example: iPhone17,2 os_version: type: string maxLength: 64 description: >- Versió del sistema operatiu del dispositiu de l'usuari final. example: 18.0.1 app_version: type: string maxLength: 64 description: Versió de la teva aplicació. example: 1.2.34 user_agent: type: string maxLength: 512 description: >- Agent d'usuari del navegador o de l'aplicació de l'usuari final. 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: >- Identificador opcional controlat per qui fa la crida (el teu id d'usuari intern, un correu electrònic, un UUID, etc.) que es manté a la sessió i es retorna a la resposta d'enviament, a la resposta de comprovació de coincidències, als webhooks i a la Business Console. Utilitza'l per correlacionar el `request_id` de Didit amb el teu registre d'usuari. metadata: type: object nullable: true description: >- Objecte JSON opcional de format lliure que es desa a la sessió i es retorna a la resposta d'enviament, a la resposta de la comprovació de coincidència, als webhooks i a la Business Console. required: - email examples: Numeric 6-digit code: summary: Per defecte — codi numèric de 6 dígits en anglès value: email: alice@example.com options: locale: en vendor_data: user-1234 Alphanumeric 8-character code: summary: Lletres majúscules + dígits, plantilla espanyola value: email: bob@example.com options: code_size: 8 alphanumeric_code: true locale: es White-label branding: summary: >- Envia el correu electrònic amb l'OTP amb la personalització de marca blanca de la teva aplicació value: email: carol@example.com options: locale: en use_white_label_customization: true vendor_data: user-5678 responses: '200': description: >- Enviament confirmat. Revisa `status`: `Success` i `Retry` indiquen que s'està enviant un codi; `Undeliverable` significa que l'adreça no pot rebre correu i la verificació ja s'ha finalitzat com a `Declined`. `request_id` és l'identificador de sessió persistit (el mateix identificador en un `Retry`). content: application/json: schema: $ref: '#/components/schemas/EmailVerificationSendResponse' examples: Success: summary: >- OTP enviat per correu electrònic per a una nova verificació (facturat) value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Success reason: null vendor_data: user-1234 metadata: null Retry: summary: >- Segon enviament dins de la finestra de 5 minuts — codi nou, mateix request_id, gratuït value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Retry reason: null vendor_data: user-1234 metadata: null Undeliverable: summary: >- L'adreça no ha superat la validació de DNS/MX: verificació finalitzada com a Rebutjada, sense facturació value: request_id: cb1a5011-344d-444d-bdce-218904745d7f status: Undeliverable reason: email_can_not_be_delivered vendor_data: user-1234 metadata: null '400': description: >- Error de validació — embolcall d'errors de camp de DRF: una matriu de missatges per camp infractor, imbricada sota `options` per a errors d'opcions. content: application/json: examples: Invalid email: summary: Adreça de correu electrònic amb format incorrecte value: email: - Enter a valid email address. Unsupported locale: summary: '`options.locale` no pertany al conjunt admès' 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` fora de l''interval 4–8' value: options: code_size: - Ensure this value is less than or equal to 8. '403': description: >- Permís denegat. Es retorna quan falta la capçalera `x-api-key` (`{"detail": ...}`); una clau incorrecta, revocada o caducada retorna `401`. També es retorna abans de qualsevol enviament quan el saldo de l'organització no pot cobrir un crèdit de l'API de Verificació de correu electrònic (`{"error": ...}`). content: application/json: examples: Missing or invalid API key: summary: >- Sense capçalera `x-api-key`, o la clau no és vàlida/s'ha revocat value: detail: You do not have permission to perform this action. Not enough credits: summary: >- El saldo de l'organització no pot cobrir el preu de l'enviament value: error: You don't have enough credits to perform this request. '429': description: >- S'ha superat el límit de freqüència. Els endpoints POST/PATCH/DELETE comparteixen un pressupost de 300 sol·licituds d'escriptura per minut per clau d'API (la creació de transaccions i la ingesta d'esdeveniments tenen un pressupost independent de 600). La resposta inclou les capçaleres `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` i `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Més de 300 sol·licituds d'escriptura en el minut actual 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: >- No s'ha pogut enviar el correu electrònic per un motiu no relacionat amb l'adreça (no s'ha pogut contactar amb el proveïdor de correu electrònic, s'ha esgotat el temps d'espera o aquest ha refusat l'enviament en si), de manera que no s'ha enviat cap codi ni s'ha facturat o comptabilitzat cap intent d'enviament. Repeteix la mateixa sol·licitud. content: application/json: examples: Email delivery unavailable: summary: >- El proveïdor de correu electrònic ha fallat després d'un reintent automàtic 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 de sessió de la verificació. Un enviament `Retry` retorna el mateix `request_id` que l'enviament original. Aquest id apareix a la Business Console, el torna a retornar un `POST /v3/email/check/` finalitzat i es pot transmetre a `GET /v3/session/{sessionId}/decision/`. status: type: string enum: - Success - Retry - Undeliverable description: >- `Success` — OTP enviat per correu electrònic a una nova verificació (facturat). `Retry` — nou OTP enviat per correu electrònic per a la verificació pendent creada per un enviament anterior (gratuït). `Undeliverable` — l'adreça no ha superat la validació de lliurabilitat o no s'ha pogut enviar el missatge; la verificació es finalitza immediatament com a `Declined` i no es factura res. reason: type: string nullable: true enum: - email_can_not_be_delivered - null description: >- `email_can_not_be_delivered` quan `status` és `Undeliverable`; `null` en cas contrari. vendor_data: type: string nullable: true description: >- Ressò de les `vendor_data` emmagatzemades a la sessió (des del primer enviament). metadata: type: object nullable: true description: >- Ressò de les `metadata` emmagatzemades a la sessió (des del primer enviament). securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.