> ## 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. # メールOTP送信API：メール認証コードを送信 > DiditのPOST /v3/email/send/でワンタイム認証コードを送信。配信不能時は自動再試行、有効期限5分、従量課金で月額最低料金なし。 ## OpenAPI ````yaml ja/openapi-25.json POST /v3/email/send/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 本人確認API。x-api-keyヘッダーで認証します。 servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/email/send/: post: tags: - Standalone APIs summary: メールコードを送信 description: >- メールアドレスにワンタイムパスコード（OTP）を送信し、[`POST /v3/email/check/`](/ja/standalone-apis/email-check)で検証します。 **送信と確認の対応関係。** 検証の状態は、アプリケーションと`email`アドレスの組み合わせで識別されます。確認の呼び出しでは`request_id`を受け取りません。新たに送信するたびに保留中の検証が作成され、その有効期間は**5分**です。期限内に、同じアドレスとユーザーが受け取ったコードを指定して確認を呼び出してください。検証が保留中の間に同じアドレスへ再度送信すると、同じ検証に対して新しいコードが生成されます（`status: "Retry"`、`request_id`は同じ）。以前のコードは使用できなくなります。この方法で追加できる再試行は最大1回です（送信は合計2回）。それ以降の送信では、新しい`request_id`で新しい検証が開始されます。5分の期間は最初の送信から計測され、再試行によって延長されることはありません。 **配信可能性の事前チェック。** 送信の前に、アドレスは構文チェックとDNS/MXの検証を受けます。メールを受信できないアドレスでは、`200`と`status: "Undeliverable"`、`reason: "email_can_not_be_delivered"`が返されます。メールは送信されず、料金も請求されず、検証は直ちに`Declined`として確定します（その後の確認では`Expired or Not Found`が返されます）。後段の送信処理が失敗した場合も同じ形で報告されます。 **コードの形式とブランディング。** コードは4〜8文字（`options.code_size`、デフォルトは6）で、デフォルトでは数字のみです。`options.alphanumeric_code: true`を設定すると英大文字と数字を使用します（確認時の比較では大文字と小文字を区別しません）。メールテンプレートは`options.locale`でローカライズでき（54言語に対応）、`options.use_white_label_customization`でアプリケーションのホワイトラベルのブランディングを使用できます。 **請求。** 送信に成功するたび（`status: "Success"`）にメールアドレス認証APIのクレジットが1つ消費され、送信時に課金されます。`Retry`と`Undeliverable`の送信は無料で、確認も無料です。 **セッションの保存。** 新しい検証はすべてAPIタイプのセッションとして保存されます。`request_id`は実際のセッションIDで、`GET /v3/session/{sessionId}/decision/`に渡すことができます。検証はBusiness Consoleに表示され、進行に応じて`status.updated`のWebhookが送信されます。 **サンドボックス。** サンドボックスのAPIキーでは配信と請求がスキップされます。リクエストの検証後（不正な入力には引き続き`400`が返されます）、エンドポイントはランダムな`request_id`を含む固定の`Success`ペイロードを返します。メールは送信されず、何も保存されません。サンドボックスでの確認にはコード`123456`を使用してください。 **認証。** アプリケーションのAPIキーを`x-api-key`ヘッダーで送信してください。認証情報がない、または無効な場合は`403`（`{"detail": "You do not have permission to perform this action."}`）が返されます。このAPIが`401`を返すことはありません。 **レート制限。** すべてのPOST/PATCH/DELETEエンドポイントで共有される書き込み枠として、APIキーごとに毎分300リクエストまでです。超過すると`429`が返されます。 operationId: post_v3email_send requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email description: >- 受信者のメールアドレス。形式が不正なアドレスは`400`を返します。構文上は有効でもメールを受信できないアドレス(DNS/MX検証に失敗したもの)は、`status: "Undeliverable"`とともに`200`を返します。 example: alice@example.com options: type: object description: OTPの形式、ローカライズ、ブランディングのオプション。すべてのフィールドは任意です。 properties: code_size: type: integer minimum: 4 maximum: 8 default: 6 description: >- OTPの文字数（デフォルトでは数字、`alphanumeric_code`が`true`の場合は英大文字と数字）。 alphanumeric_code: type: boolean default: false description: >- `true`の場合、OTPは数字のみではなく、大文字`A–Z`と数字`0–9`で構成されます。`/v3/email/check/`での照合では、大文字と小文字は区別されません。 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: >- OTPメールテンプレートの言語。デフォルトは`en`です。対応していない値を指定すると`400`が返され、対応しているすべてのロケールが一覧表示されます。 example: en use_white_label_customization: type: boolean default: false description: >- `true`の場合、OTPメールにはデフォルトのDiditテンプレートではなく、アプリケーションのホワイトラベルのカスタマイズ（ロゴ、色、送信者のブランディング）が使用されます。 signals: type: object description: >- エンドユーザーに関するデバイスおよびネットワークの任意のシグナルで、不正利用や自動化されたトラフィックの検出精度を高めるために不正対策レイヤーへ転送されます。すべてのフィールドは任意です。 properties: ip: type: string description: エンドユーザーのデバイスのIPアドレス。IPv4またはIPv6。 example: 192.0.2.1 device_id: type: string maxLength: 255 description: >- エンドユーザーのデバイスの一意の識別子。Android:`ANDROID_ID`、iOS:`identifierForVendor`。 example: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: type: string enum: - android - ios - ipados - tvos - web description: エンドユーザーのデバイスのプラットフォーム。 device_model: type: string maxLength: 255 description: エンドユーザーのデバイスの機種。 example: iPhone17,2 os_version: type: string maxLength: 64 description: エンドユーザーのデバイスのオペレーティングシステムのバージョンです。 example: 18.0.1 app_version: type: string maxLength: 64 description: アプリケーションのバージョン。 example: 1.2.34 user_agent: type: string maxLength: 512 description: エンドユーザーのブラウザまたはアプリのユーザーエージェント。 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: >- 呼び出し側が管理する任意の識別子（社内のユーザーid、メールアドレス、UUIDなど）です。セッションに保存され、送信レスポンス、対応するチェックレスポンス、Webhook、Business Consoleでそのまま返されます。Diditの`request_id`を自社のユーザーレコードと関連付けるために使用してください。 metadata: type: object nullable: true description: >- セッションに保存される任意の自由形式のJSONオブジェクトです。送信レスポンス、対応するチェックのレスポンス、Webhook、Business Consoleでそのまま返されます。 required: - email examples: Numeric 6-digit code: summary: デフォルト：英語の6桁の数字コード value: email: alice@example.com options: locale: en vendor_data: user-1234 Alphanumeric 8-character code: summary: 大文字の英字と数字、スペイン向けテンプレート value: email: bob@example.com options: code_size: 8 alphanumeric_code: true locale: es White-label branding: summary: アプリケーションのホワイトラベルのカスタマイズを適用してOTPメールを送信する value: email: carol@example.com options: locale: en use_white_label_customization: true vendor_data: user-5678 responses: '200': description: >- 送信を受け付けました。`status`を確認してください。`Success`と`Retry`はコードが送信中であることを示し、`Undeliverable`はそのアドレスがメールを受信できず、認証がすでに`Declined`として確定済みであることを示します。`request_id`は永続化されたセッションIDです（`Retry`の場合も同じIDです）。 content: application/json: schema: $ref: '#/components/schemas/EmailVerificationSendResponse' examples: Success: summary: 新規認証のためにOTPをメールで送信しました(課金対象) value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Success reason: null vendor_data: user-1234 metadata: null Retry: summary: 5分間のウィンドウ内での2回目の送信（新しいコード、同じrequest_id、無料） value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Retry reason: null vendor_data: user-1234 metadata: null Undeliverable: summary: アドレスがDNS/MX検証に失敗しました。検証は却下として確定し、課金は発生しません value: request_id: cb1a5011-344d-444d-bdce-218904745d7f status: Undeliverable reason: email_can_not_be_delivered vendor_data: user-1234 metadata: null '400': description: >- 検証エラー：DRFのフィールドエラーエンベロープです。問題のあるフィールドごとにメッセージの配列が1つ返され、オプションのエラーは`options`の下にネストされます。 content: application/json: examples: Invalid email: summary: メールアドレスの形式が不正です value: email: - Enter a valid email address. Unsupported locale: summary: '`options.locale`がサポート対象外' 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`が4〜8の範囲外' value: options: code_size: - Ensure this value is less than or equal to 8. '403': description: >- 権限がありません。`x-api-key`ヘッダーがない場合に返されます（`{"detail": ...}`）。誤った、取り消された、または期限切れのキーの場合は`401`が返されます。また、組織の残高がメールアドレス認証APIのクレジット1件分を賄えない場合にも、送信前に返されます（`{"error": ...}`）。 content: application/json: examples: Missing or invalid API key: summary: '`x-api-key`ヘッダーがないか、キーが無効または失効しています' value: detail: You do not have permission to perform this action. Not enough credits: summary: 組織の残高で送信料金を賄えません value: error: You don't have enough credits to perform this request. '429': description: >- レート制限を超過しました。すべてのPOST/PATCH/DELETEエンドポイントは、APIキーごとに1分あたり300件の書き込みリクエストという共通の上限を共有します。レスポンスには`X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset`、`Retry-After`ヘッダーが含まれます。 content: application/json: examples: Write rate limit exceeded: summary: 現在の1分間に300件を超える書き込みリクエスト 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: >- メールプロバイダーに接続できなかったため（障害またはタイムアウト）、コードは送信されず、課金も送信試行としてのカウントも行われていません。同じリクエストを再度送信してください。 content: application/json: examples: Email delivery unavailable: summary: 1回の自動再試行の後もメールプロバイダーでエラーが発生しました 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。`Retry`による送信では、元の送信と同じ`request_id`が返されます。このIDはBusiness Consoleに表示され、確定済みの`POST /v3/email/check/`でも再度返され、`GET /v3/session/{sessionId}/decision/`に渡すことができます。 status: type: string enum: - Success - Retry - Undeliverable description: >- `Success`：新しい認証にOTPをメールで送信しました（課金対象）。`Retry`：以前の送信で作成された保留中の認証に対して、新しいOTPをメールで送信しました（無料）。`Undeliverable`：メールアドレスが配信可能性の検証に失敗したか、メッセージを送信できませんでした。認証は直ちに`Declined`として確定し、課金は発生しません。 reason: type: string nullable: true enum: - email_can_not_be_delivered - null description: >- `status`が`Undeliverable`の場合は`email_can_not_be_delivered`、それ以外の場合は`null`。 vendor_data: type: string nullable: true description: セッションに保存されている`vendor_data`（最初の送信時のもの）のエコー。 metadata: type: object nullable: true description: セッションに保存されている`metadata`（最初の送信時のもの）のエコー。 securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- お客様のアプリケーションのAPIキーです。Business ConsoleのDevelopers -> API keysで取得できます。プライマリキーはフルアクセス権を持ちます。名前付きキーにはスコープを設定できます。リソースごとのアクセス権（なし、読み取り、書き込み）、一部のワークフローまたは承認済みセッションへの限定、IPアドレスのリストへの限定、有効期限の設定です。401は、キーが誤っている、失効している、または期限切れであることを意味します。403は、キーが送信されていない、キーにこのリソースやアクションへのアクセス権がない、またはIPリスト外のアドレスからリクエストが送信されたことを意味します。セッションのルートでの404は、セッションがキーのワークフローまたはステータスの対象外であることを意味します。メディアへのアクセス権がないキーでは、画像、動画、PDFのURLがnullで返されます。セッションの書き込み権限がないキーでは、セッションのリンクとトークンがnullで返されます。詳細は次を参照してください: https://docs.didit.me/console/api-keys ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.