> ## 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. # E-Mail-Verifizierung: Einmalcode per API senden > Didit sendet per POST /v3/email/send/ einen Einmalcode per E-Mail. Auto-Wiederholung, 5 Min. gültig, Preis pro Aufruf, keine Mindestumsätze. ## OpenAPI ````yaml de/openapi-25.json POST /v3/email/send/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API für Ausweisverifizierung. Authentifizierung über den x-api-key-Header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/email/send/: post: tags: - Standalone APIs summary: E-Mail-Code senden description: >- Senden Sie einen Einmalcode (OTP) an eine E-Mail-Adresse und verifizieren Sie ihn anschließend mit [`POST /v3/email/check/`](/de/standalone-apis/email-check). **Zusammenspiel von Senden und Prüfen.** Der Verifizierungsstatus wird über Ihre Anwendung und die `email`-Adresse zugeordnet – der Prüfaufruf benötigt keine `request_id`. Jeder neue Sendeaufruf erstellt eine ausstehende Verifizierung, die **5 Minuten** lang gültig ist: Rufen Sie die Prüfung mit derselben Adresse und dem Code auf, den der Benutzer erhalten hat, bevor das Zeitfenster abläuft. Wenn Sie für dieselbe Adresse erneut senden, während eine Verifizierung aussteht, wird ein neuer Code für dieselbe Verifizierung generiert (`status: "Retry"`, dieselbe `request_id`); der vorherige Code verliert seine Gültigkeit. Auf diese Weise ist höchstens ein Wiederholungsversuch verknüpft (insgesamt zwei Sendeaufrufe); ein weiteres Senden startet eine neue Verifizierung mit einer neuen `request_id`. Das 5-Minuten-Zeitfenster wird ab dem ersten Senden gemessen und durch Wiederholungsversuche nicht verlängert. **Vorabprüfung der Zustellbarkeit.** Bevor etwas gesendet wird, durchläuft die Adresse eine Syntax- und DNS/MX-Validierung. Adressen, die keine E-Mails empfangen können, geben `200` mit `status: "Undeliverable"` und `reason: "email_can_not_be_delivered"` zurück – es wird keine E-Mail gesendet, nichts in Rechnung gestellt und die Verifizierung wird sofort als `Declined` abgeschlossen (eine nachfolgende Prüfung gibt `Expired or Not Found` zurück). Ein Sendeversuch, der aus einem anderen Grund fehlschlägt (die E-Mail konnte nicht zur Zustellung übergeben werden), gibt stattdessen `503` zurück: Es wird kein Code gesendet, nichts in Rechnung gestellt, die Verifizierung bleibt offen und dieselbe Anfrage kann wiederholt werden. **Code-Format und Branding.** Codes bestehen aus 4–8 Zeichen (`options.code_size`, standardmäßig 6), standardmäßig numerisch; setzen Sie `options.alphanumeric_code: true` für Großbuchstaben und Ziffern (der Vergleich bei der Prüfung unterscheidet nicht zwischen Groß- und Kleinschreibung). Die E-Mail-Vorlage wird über `options.locale` lokalisiert (54 unterstützte Sprachen) und kann über `options.use_white_label_customization` das White-Label-Branding Ihrer Anwendung nutzen. **Abrechnung.** Ein Credit für die E-Mail-Verifizierungs-API pro erfolgreichem Senden (`status: "Success"`), abgerechnet zum Zeitpunkt des Sendens. `Retry`- und `Undeliverable`-Sendeaufrufe sind kostenlos, und Prüfungen sind ebenfalls kostenlos. **Persistenz von Sitzungen.** Jede neue Verifizierung wird als Sitzung vom Typ API beibehalten: `request_id` ist eine echte Sitzungs-ID, die Sie an `GET /v3/session/{sessionId}/decision/` übergeben können, die Verifizierung erscheint in der Business Console und `status.updated`-Webhooks werden im Verlauf ausgelöst. **Sandbox.** Sandbox-API-Schlüssel überspringen Zustellung und Abrechnung: Nach der Anfragevalidierung (fehlerhafte Eingaben geben weiterhin `400` zurück) gibt der Endpoint eine statische `Success`-Payload mit einer zufälligen `request_id` zurück; es wird keine E-Mail gesendet und nichts gespeichert. Verwenden Sie den Code `123456` für die Prüfung in der Sandbox. **Authentifizierung.** Senden Sie den API-Schlüssel Ihrer Anwendung im Header `x-api-key`. Fehlende oder ungültige Anmeldedaten geben `403` zurück (`{"detail": "You do not have permission to perform this action."}`) – diese API gibt niemals `401` zurück. **Rate-Limit.** Geteiltes Schreibkontingent von 300 Anfragen/Min. pro API-Schlüssel über alle POST/PATCH/DELETE-Endpoints hinweg; bei Überschreitung wird `429` zurückgegeben. operationId: post_v3email_send requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email description: >- Empfänger-E-Mail-Adresse. Ungültig formatierte Adressen geben `400` zurück; syntaktisch gültige Adressen, die keine E-Mails empfangen können (fehlgeschlagene DNS-/MX-Validierung), geben `200` mit `status: "Undeliverable"` zurück. example: alice@example.com options: type: object description: >- Optionen für OTP-Format, Lokalisierung und Branding. Alle Felder sind optional. properties: code_size: type: integer minimum: 4 maximum: 8 default: 6 description: >- Anzahl der Zeichen im OTP (standardmäßig Ziffern; Großbuchstaben und Ziffern, wenn `alphanumeric_code` `true` ist). alphanumeric_code: type: boolean default: false description: >- Wenn `true`, besteht das OTP aus Großbuchstaben `A–Z` und Ziffern `0–9` anstelle von reinen Ziffern. Der Vergleich von `/v3/email/check/` unterscheidet nicht zwischen Groß- und Kleinschreibung. 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: >- Sprache der OTP-E-Mail-Vorlage. Standardmäßig `en`. Nicht unterstützte Werte geben `400` zurück und führen alle unterstützten Gebietsschemata auf. example: en use_white_label_customization: type: boolean default: false description: >- Wenn `true`, verwendet die OTP-E-Mail die White-Label-Anpassung Ihrer Anwendung (Logo, Farben, Absender-Branding) anstelle der standardmäßigen Didit-Vorlage. signals: type: object description: >- Optionale Geräte- und Netzwerksignale über den Endbenutzer, die an die Betrugsbekämpfungsebene weitergeleitet werden, um die Erkennung von missbräuchlichem oder automatisiertem Datenverkehr zu verbessern. Alle Felder sind optional. properties: ip: type: string description: IP-Adresse des Endbenutzergeräts. IPv4 oder IPv6. example: 192.0.2.1 device_id: type: string maxLength: 255 description: >- Eindeutige Kennung des Geräts des Endbenutzers. Android: `ANDROID_ID`; iOS: `identifierForVendor`. example: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: type: string enum: - android - ios - ipados - tvos - web description: Plattform des Geräts des Endbenutzers. device_model: type: string maxLength: 255 description: Modell des Geräts des Endbenutzers. example: iPhone17,2 os_version: type: string maxLength: 64 description: Betriebssystemversion des Geräts des Endbenutzers. example: 18.0.1 app_version: type: string maxLength: 64 description: Version Ihrer Anwendung. example: 1.2.34 user_agent: type: string maxLength: 512 description: User-Agent des Browsers oder der App des Endbenutzers. 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: >- Optionale, vom Aufrufer gesteuerte Kennung (Ihre interne Benutzer-ID, eine E-Mail-Adresse, eine UUID usw.), die in der Sitzung gespeichert und in der Antwort auf den Sendevorgang, der Antwort auf die Abgleichprüfung, Webhooks und der Business Console zurückgegeben wird. Verwenden Sie sie, um Didits `request_id` mit Ihrem Benutzerdatensatz zu korrelieren. metadata: type: object nullable: true description: >- Optionales Freiform-JSON-Objekt, das in der Sitzung gespeichert und in der Sendeantwort, der Antwort der Abgleichprüfung, in Webhooks sowie in der Business Console wiedergegeben wird. required: - email examples: Numeric 6-digit code: summary: Standard – 6-stelliger numerischer Code auf Englisch value: email: alice@example.com options: locale: en vendor_data: user-1234 Alphanumeric 8-character code: summary: Großbuchstaben + Ziffern, spanische Vorlage value: email: bob@example.com options: code_size: 8 alphanumeric_code: true locale: es White-label branding: summary: >- Senden Sie die OTP-E-Mail mit der White-Label-Anpassung Ihrer Anwendung value: email: carol@example.com options: locale: en use_white_label_customization: true vendor_data: user-5678 responses: '200': description: >- Versand bestätigt. Prüfen Sie `status`: `Success` und `Retry` bedeuten, dass ein Code unterwegs ist; `Undeliverable` bedeutet, dass die Adresse keine Post empfangen kann und die Verifizierung bereits als `Declined` abgeschlossen ist. `request_id` ist die gespeicherte Sitzungs-ID (dieselbe ID bei einem `Retry`). content: application/json: schema: $ref: '#/components/schemas/EmailVerificationSendResponse' examples: Success: summary: >- OTP per E-Mail für eine neue Verifizierung gesendet (abgerechnet) value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Success reason: null vendor_data: user-1234 metadata: null Retry: summary: >- Zweiter Versand innerhalb des 5-Minuten-Fensters — neuer Code, identische request_id, kostenlos value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Retry reason: null vendor_data: user-1234 metadata: null Undeliverable: summary: >- Adresse hat die DNS/MX-Validierung nicht bestanden – Verifizierung als abgelehnt abgeschlossen, nichts abgerechnet value: request_id: cb1a5011-344d-444d-bdce-218904745d7f status: Undeliverable reason: email_can_not_be_delivered vendor_data: user-1234 metadata: null '400': description: >- Validierungsfehler – DRFs Feldfehler-Envelope: ein Array von Meldungen pro fehlerhaftem Feld, bei Optionsfehlern unter `options` geschachtelt. content: application/json: examples: Invalid email: summary: Ungültige E-Mail-Adresse value: email: - Enter a valid email address. Unsupported locale: summary: '`options.locale` außerhalb der unterstützten Auswahl' 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` außerhalb von 4–8' value: options: code_size: - Ensure this value is less than or equal to 8. '403': description: >- Zugriff verweigert. Wird zurückgegeben, wenn der Header `x-api-key` fehlt (`{"detail": ...}`); ein falscher, widerrufener oder abgelaufener Schlüssel gibt `401` zurück. Wird auch vor jedem Senden zurückgegeben, wenn das Guthaben der Organisation einen Credit der E-Mail-Verifizierungs-API nicht decken kann (`{"error": ...}`). content: application/json: examples: Missing or invalid API key: summary: >- Kein `x-api-key`-Header, oder der Schlüssel ist ungültig/widerrufen value: detail: You do not have permission to perform this action. Not enough credits: summary: >- Das Guthaben der Organisation reicht für den Preis des Versands nicht aus value: error: You don't have enough credits to perform this request. '429': description: >- Rate-Limit überschritten. POST/PATCH/DELETE-Endpoints teilen sich ein Budget von 300 Schreibanfragen pro Minute pro API-Schlüssel (Transaktionserstellungen und Ereignis-Ingestion haben ein separates Budget von 600). Die Antwort enthält die Header `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` und `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Mehr als 300 Schreibanfragen in der aktuellen Minute 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: >- Die E-Mail konnte aus einem Grund, der nicht mit der Adresse zusammenhängt, nicht gesendet werden (der E-Mail-Anbieter konnte nicht erreicht werden, hatte ein Timeout oder lehnte den Versand selbst ab), sodass kein Code gesendet und nichts abgerechnet oder als Sendeversuch gezählt wurde. Wiederholen Sie dieselbe Anfrage. content: application/json: examples: Email delivery unavailable: summary: >- Der E-Mail-Anbieter ist nach einem automatischen Wiederholungsversuch ausgefallen 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: >- Sitzungs-ID der Verifizierung. Ein `Retry`-Sendevorgang gibt dieselbe `request_id` wie der ursprüngliche Sendevorgang zurück. Diese ID erscheint in der Business Console, wird von einem finalisierten `POST /v3/email/check/` erneut zurückgegeben und kann an `GET /v3/session/{sessionId}/decision/` übergeben werden. status: type: string enum: - Success - Retry - Undeliverable description: >- `Success` — OTP per E-Mail an eine neue Verifizierung gesendet (abgerechnet). `Retry` — neuer OTP per E-Mail für die ausstehende Verifizierung gesendet, die durch einen vorherigen Versand erstellt wurde (kostenlos). `Undeliverable` — die Adresse hat die Zustellbarkeitsvalidierung nicht bestanden oder die Nachricht konnte nicht gesendet werden; die Verifizierung wird sofort als `Declined` abgeschlossen und es wird nichts abgerechnet. reason: type: string nullable: true enum: - email_can_not_be_delivered - null description: >- `email_can_not_be_delivered`, wenn `status` `Undeliverable` ist; andernfalls `null`. vendor_data: type: string nullable: true description: >- Rückgabe der in der Sitzung gespeicherten `vendor_data` (aus dem ersten Senden). metadata: type: object nullable: true description: >- Rückgabe der in der Sitzung gespeicherten `metadata` (aus dem ersten Senden). securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Der API-Schlüssel Ihrer Anwendung, aus Entwickler -> API-Schlüssel in der Business Console. Der Primärschlüssel hat Vollzugriff. Ein benannter Schlüssel kann im Geltungsbereich eingeschränkt werden: keine, Lese- oder Schreibberechtigung pro Ressource, beschränkt auf bestimmte Workflows oder genehmigte Sitzungen, auf eine Liste von IP-Adressen und auf ein Ablaufdatum. 401 bedeutet, dass der Schlüssel falsch, widerrufen oder abgelaufen ist; 403 bedeutet, dass kein Schlüssel gesendet wurde, der Schlüssel keinen Zugriff auf diese Ressource oder Aktion hat oder die Anfrage von einer Adresse außerhalb seiner IP-Liste stammte; 404 bei einer Sitzungsroute bedeutet, dass die Sitzung außerhalb der Workflows oder Status des Schlüssels liegt. Ein Schlüssel ohne Medienzugriff erhält Bild-, Video- und PDF-URLs als null, und ein Schlüssel ohne Schreibberechtigung für Sitzungen erhält Sitzungslinks und Token als null. Siehe https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.