> ## 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 d'envoi de code OTP par e-mail : Vérification e-mail > Envoyez un code à usage unique par e-mail avec Didit via POST /v3/email/send/. Nouvel essai auto, validité 5 min, paiement à l'usage, sans minimum. ## OpenAPI ````yaml fr/openapi-25.json POST /v3/email/send/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de vérification d'identité. Authentifiez-vous avec l'en-tête x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/email/send/: post: tags: - Standalone APIs summary: Envoyer le code par e-mail description: "Envoyez un code à usage unique (OTP) à une adresse e-mail, puis vérifiez-le avec [`POST /v3/email/check/`](/fr/standalone-apis/email-check).\n\n**Association entre l'envoi et la vérification.** L'état de la vérification est indexé par votre application et l'adresse `email` — l'appel de vérification ne prend pas de `request_id`. Chaque nouvel envoi crée une vérification en attente qui reste active pendant **5 minutes**\_: appelez la vérification avec la même adresse et le code reçu par l'utilisateur avant la fin du délai. Appeler à nouveau l'envoi pour la même adresse alors qu'une vérification est en attente génère un nouveau code pour cette même vérification (`status: \"Retry\"`, même `request_id`)\_; le code précédent cesse de fonctionner. Au maximum une nouvelle tentative est associée de cette façon (deux envois au total)\_; un envoi supplémentaire démarre une nouvelle vérification avec un nouveau `request_id`. La fenêtre de 5 minutes est mesurée à partir du premier envoi et n'est pas prolongée par les nouvelles tentatives.\n\n**Pré-vérification de délivrabilité.** Avant tout envoi, l'adresse fait l'objet d'une validation syntaxique et DNS/MX. Les adresses qui ne peuvent pas recevoir d'e-mails renvoient `200` avec `status: \"Undeliverable\"` et `reason: \"email_can_not_be_delivered\"` — aucun e-mail n'est envoyé, rien n'est facturé et la vérification est immédiatement finalisée comme `Declined` (une vérification ultérieure renvoie `Expired or Not Found`). Un envoi qui échoue pour une raison non liée à l'adresse (l'e-mail n'a pas pu être transmis pour livraison) renvoie `503` à la place\_: aucun code n'est envoyé, rien n'est facturé, la vérification reste ouverte et la même requête peut être réitérée.\n\n**Format du code et personnalisation.** Les codes comportent de 4 à 8 caractères (`options.code_size`, 6 par défaut), numériques par défaut\_; définissez `options.alphanumeric_code: true` pour des lettres majuscules et des chiffres (la comparaison lors de la vérification est insensible à la casse). Le modèle d'e-mail est localisé via `options.locale` (54 langues prises en charge) et peut utiliser la personnalisation en marque blanche de votre application via `options.use_white_label_customization`.\n\n**Facturation.** Un crédit d'API de Vérification de l'e-mail par envoi réussi (`status: \"Success\"`), débité au moment de l'envoi. Les envois `Retry` et `Undeliverable` sont gratuits, et les vérifications sont gratuites.\n\n**Persistance des sessions.** Chaque nouvelle vérification est conservée sous la forme d'une session de type API\_: `request_id` est un véritable identifiant de session que vous pouvez transmettre à `GET /v3/session/{sessionId}/decision/`, la vérification apparaît dans la Business Console et les webhooks `status.updated` se déclenchent au fur et à mesure de sa progression.\n\n**Sandbox.** Les clés API sandbox ignorent la livraison et la facturation\_: après la validation de la requête (une entrée malformée renvoie toujours `400`), l'endpoint renvoie un payload statique `Success` avec un `request_id` aléatoire\_; aucun e-mail n'est envoyé et rien n'est conservé. Utilisez le code `123456` lors de la vérification en sandbox.\n\n**Authentification.** Envoyez la clé API de votre application dans l'en-tête `x-api-key`. Des identifiants manquants ou invalides renvoient `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — cette API ne renvoie jamais `401`.\n\n**Limite de débit.** Budget d'écriture partagé de 300 requêtes/min par clé API sur l'ensemble des endpoints POST/PATCH/DELETE\_; tout dépassement renvoie `429`." operationId: post_v3email_send requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email description: >- Adresse e-mail du destinataire. Les adresses malformées renvoient `400` ; les adresses syntaxiquement valides mais incapables de recevoir des e-mails (échec de validation DNS/MX) renvoient `200` avec `status: "Undeliverable"`. example: alice@example.com options: type: object description: >- Options de format, de localisation et d'image de marque de l'OTP. Tous les champs sont facultatifs. properties: code_size: type: integer minimum: 4 maximum: 8 default: 6 description: >- Nombre de caractères dans l'OTP (chiffres par défaut ; lettres majuscules et chiffres lorsque `alphanumeric_code` est `true`). alphanumeric_code: type: boolean default: false description: >- Lorsque la valeur est `true`, l'OTP est composé de lettres majuscules `A–Z` et de chiffres `0–9` au lieu de chiffres uniquement. La comparaison effectuée par `/v3/email/check/` est insensible à la casse. 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: >- Langue du modèle d'e-mail OTP. La valeur par défaut est `en`. Les valeurs non prises en charge renvoient une erreur `400` listant toutes les langues acceptées. example: en use_white_label_customization: type: boolean default: false description: >- Lorsque la valeur est `true`, l'e-mail OTP utilise la personnalisation en marque blanche de votre application (logo, couleurs, image de marque de l'expéditeur) au lieu du modèle Didit par défaut. signals: type: object description: >- Signaux d'appareil et de réseau optionnels concernant l'utilisateur final, transmis à la couche antifraude pour améliorer la détection de trafic abusif ou automatisé. Tous les champs sont optionnels. properties: ip: type: string description: >- Adresse de l'appareil de l'utilisateur final. IPv4 ou IPv6. example: 192.0.2.1 device_id: type: string maxLength: 255 description: >- Identifiant unique de l'appareil de l'utilisateur final. Android : `ANDROID_ID` ; iOS : `identifierForVendor`. example: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: type: string enum: - android - ios - ipados - tvos - web description: Plateforme de l'appareil de l'utilisateur final. device_model: type: string maxLength: 255 description: Modèle de l'appareil de l'utilisateur final. example: iPhone17,2 os_version: type: string maxLength: 64 description: >- Version du système d'exploitation de l'appareil de l'utilisateur final. example: 18.0.1 app_version: type: string maxLength: 64 description: Version de votre application. example: 1.2.34 user_agent: type: string maxLength: 512 description: >- Agent utilisateur du navigateur ou de l'application de l'utilisateur 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: >- Identifiant optionnel contrôlé par l'appelant (votre identifiant utilisateur interne, un e-mail, un UUID, etc.) persisté sur la session et renvoyé dans la réponse d'envoi, la réponse de vérification de correspondance, les webhooks et la Business Console. Utilisez-le pour corréler le `request_id` de Didit avec votre dossier utilisateur. metadata: type: object nullable: true description: >- Objet JSON libre optionnel conservé sur la session et renvoyé dans la réponse d'envoi, la réponse de vérification de correspondance, les webhooks et la Business Console. required: - email examples: Numeric 6-digit code: summary: Par défaut — code numérique à 6 chiffres en anglais value: email: alice@example.com options: locale: en vendor_data: user-1234 Alphanumeric 8-character code: summary: Lettres majuscules + chiffres, modèle espagnol value: email: bob@example.com options: code_size: 8 alphanumeric_code: true locale: es White-label branding: summary: >- Envoyez l'e-mail contenant l'OTP avec la personnalisation en marque blanche de votre application value: email: carol@example.com options: locale: en use_white_label_customization: true vendor_data: user-5678 responses: '200': description: >- Envoi pris en compte. Examinez `status` : `Success` et `Retry` indiquent qu'un code est en cours d'envoi ; `Undeliverable` signifie que l'adresse ne peut pas recevoir d'e-mails et que la vérification est déjà finalisée en tant que `Declined`. `request_id` est l'identifiant de session persistant (même identifiant lors d'un `Retry`). content: application/json: schema: $ref: '#/components/schemas/EmailVerificationSendResponse' examples: Success: summary: >- OTP envoyé par e-mail pour une nouvelle vérification (facturé) value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Success reason: null vendor_data: user-1234 metadata: null Retry: summary: >- Deuxième envoi dans la fenêtre de 5 minutes — nouveau code, même request_id, gratuit value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Retry reason: null vendor_data: user-1234 metadata: null Undeliverable: summary: >- Échec de la validation DNS/MX de l'adresse — vérification finalisée avec le statut Refusé, aucune facturation value: request_id: cb1a5011-344d-444d-bdce-218904745d7f status: Undeliverable reason: email_can_not_be_delivered vendor_data: user-1234 metadata: null '400': description: >- Erreur de validation — enveloppe d'erreur de champ de DRF : un tableau de messages par champ concerné, imbriqué sous `options` pour les erreurs d'options. content: application/json: examples: Invalid email: summary: Adresse e-mail mal formée value: email: - Enter a valid email address. Unsupported locale: summary: '`options.locale` en dehors de l''ensemble pris en charge' 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` en dehors de la plage 4–8' value: options: code_size: - Ensure this value is less than or equal to 8. '403': description: "Permission refusée. Renvoyé lorsque l'en-tête `x-api-key` est manquant (`{\"detail\": ...}`)\_; une clé incorrecte, révoquée ou expirée renvoie `401`. Également renvoyé avant tout envoi lorsque le solde de l'organisation ne permet pas de couvrir un crédit de l'API Vérification de l'e-mail (`{\"error\": ...}`)." content: application/json: examples: Missing or invalid API key: summary: Aucun en-tête `x-api-key`, ou la clé est non valide/révoquée value: detail: You do not have permission to perform this action. Not enough credits: summary: >- Le solde de l'organisation ne peut pas couvrir le prix d'envoi value: error: You don't have enough credits to perform this request. '429': description: >- Limite de débit dépassée. Les endpoints POST/PATCH/DELETE partagent un budget de 300 requêtes d'écriture par minute par clé API (la création de transactions et l'ingestion d'événements ont un budget distinct de 600). La réponse comporte les en-têtes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` et `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: >- Plus de 300 requêtes d'écriture au cours de la minute actuelle 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: >- L'e-mail n'a pas pu être envoyé pour une raison indépendante de l'adresse (le fournisseur de messagerie n'a pas pu être joint, a dépassé le délai d'attente ou a refusé lui-même l'envoi) : aucun code n'a donc été envoyé et rien n'a été facturé ni comptabilisé comme tentative d'envoi. Réessayez la même requête. content: application/json: examples: Email delivery unavailable: summary: >- Le fournisseur d'e-mail a échoué après une tentative automatique 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 session de la vérification. Un envoi `Retry` renvoie le même `request_id` que l'envoi initial. Cet identifiant apparaît dans la Business Console, est renvoyé à nouveau par un `POST /v3/email/check/` finalisé, et peut être transmis à `GET /v3/session/{sessionId}/decision/`. status: type: string enum: - Success - Retry - Undeliverable description: >- `Success` — OTP envoyé par e-mail pour une nouvelle vérification (facturé). `Retry` — nouvel OTP envoyé par e-mail pour la vérification en attente créée par un envoi précédent (gratuit). `Undeliverable` — l'adresse n'a pas passé la validation de délivrabilité ou le message n'a pas pu être envoyé ; la vérification est immédiatement finalisée comme `Declined` et rien n'est facturé. reason: type: string nullable: true enum: - email_can_not_be_delivered - null description: >- `email_can_not_be_delivered` lorsque `status` est `Undeliverable` ; `null` dans le cas contraire. vendor_data: type: string nullable: true description: >- Écho des `vendor_data` stockées sur la session (depuis le premier envoi). metadata: type: object nullable: true description: >- Écho des `metadata` stockées sur la session (depuis le premier envoi). securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- La clé API de votre application, issue de Développeurs -> Clés API dans la Business Console. La clé principale dispose d'un accès complet. Une clé nommée peut être restreinte : aucun, lecture ou écriture par ressource, limitée à certains workflows ou aux sessions approuvées, à une liste d'adresses IP et à une date d'expiration. 401 signifie que la clé est incorrecte, révoquée ou expirée ; 403 signifie qu'aucune clé n'a été envoyée, que la clé n'a pas accès à cette ressource ou action, ou que la requête provient d'une adresse hors de sa liste d'IP ; 404 sur une route de session signifie que la session est hors des workflows ou des statuts de la clé. Une clé sans accès aux médias reçoit les URL d'images, de vidéos et de PDF à null, et une clé sans accès en écriture aux sessions reçoit les liens et tokens de session à null. Voir https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.