> ## 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 отправки кода на email: проверка электронной почты > POST /v3/email/send/ отправляет одноразовый код подтверждения. Автоповтор при недоставке, срок действия 5 минут, оплата за вызов без месячного минимума. Didit. ## OpenAPI ````yaml ru/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: Отправить код на email description: >- Отправьте одноразовый код (OTP) на адрес электронной почты, затем проверьте его с помощью [`POST /v3/email/check/`](/ru/standalone-apis/email-check). **Как связаны отправка и проверка.** Состояние верификации привязано к вашему приложению и адресу `email` — вызов проверки не принимает `request_id`. Каждая новая отправка создаёт незавершённую верификацию со сроком жизни **5 минут**: вызовите проверку с тем же адресом и кодом, полученным пользователем, до закрытия этого окна. Повторный вызов отправки для того же адреса при наличии незавершённой верификации генерирует новый код для той же верификации (`status: "Retry"`, тот же `request_id`); предыдущий код перестаёт действовать. Таким образом привязывается не более одной повторной попытки (всего две отправки); следующая отправка начинает новую верификацию с новым `request_id`. 5-минутное окно отсчитывается от первой отправки и не продлевается повторными попытками. **Предварительная проверка доставляемости.** Перед отправкой адрес проходит синтаксическую валидацию и проверку DNS/MX. Для адресов, которые не могут принимать почту, возвращается `200` со `status: "Undeliverable"` и `reason: "email_can_not_be_delivered"` — письмо не отправляется, средства не списываются, а верификация сразу завершается со статусом `Declined` (последующая проверка возвращает `Expired or Not Found`). Отправка, завершившаяся сбоем по причине, не связанной с адресом (письмо не удалось передать для доставки), возвращает вместо этого `503`: код не отправляется, средства не списываются, верификация остаётся открытой, и тот же запрос можно повторить. **Формат кода и брендинг.** Коды состоят из 4–8 символов (`options.code_size`, по умолчанию 6) и по умолчанию являются числовыми; задайте `options.alphanumeric_code: true` для использования заглавных букв и цифр (сравнение при проверке нечувствительно к регистру). Шаблон письма локализуется через `options.locale` (поддерживается 54 языка) и может использовать оформление White label вашего приложения с помощью `options.use_white_label_customization`. **Биллинг.** За каждую успешную отправку (`status: "Success"`) в момент отправки списывается один кредит API Проверки электронной почты. Отправки со статусом `Retry` и `Undeliverable` бесплатны, проверки также бесплатны. **Сохранение сессии.** Каждая новая верификация сохраняется как сессия типа API: `request_id` представляет собой реальный идентификатор сессии, который можно передать в `GET /v3/session/{sessionId}/decision/`, верификация отображается в Business Console, а по мере её выполнения отправляются события webhook `status.updated`. **Песочница.** API-ключи песочницы пропускают доставку и биллинг: после валидации запроса (некорректный ввод по-прежнему возвращает `400`) endpoint возвращает статический payload `Success` со случайным `request_id`; письмо не отправляется и данные не сохраняются. При проверке в песочнице используйте код `123456`. **Аутентификация.** Передавайте API-ключ вашего приложения в заголовке `x-api-key`. При отсутствии или недействительности учётных данных возвращается `403` (`{"detail": "You do not have permission to perform this action."}`) — этот API никогда не возвращает `401`. **Лимит запросов.** Общий лимит на запись составляет 300 запросов/мин на один API-ключ для всех endpoints POST/PATCH/DELETE; при его превышении возвращается `429`. operationId: post_v3email_send requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email description: >- Адрес электронной почты получателя. Некорректные адреса возвращают `400`; синтаксически корректные адреса, не способные принимать почту (неудачная проверка DNS/MX), возвращают `200` со значением `status: "Undeliverable"`. example: alice@example.com options: type: object description: >- Параметры формата, локализации и брендинга одноразового кода. Все поля необязательны. 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 используется кастомизация White label вашего приложения (логотип, цвета, брендинг отправителя) вместо стандартного шаблона 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: >- User-Agent браузера или приложения конечного пользователя. 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: >- Необязательный идентификатор, контролируемый вызывающей стороной (ваш внутренний идентификатор пользователя, email, UUID и т. д.), сохраняемый в сессии и возвращаемый в ответе на отправку, ответе проверки соответствия, webhook и Business Console. Используйте его для сопоставления `request_id` от Didit с вашей записью пользователя. 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-письмо с настройками White label вашего приложения 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`). content: application/json: schema: $ref: '#/components/schemas/EmailVerificationSendResponse' examples: Success: summary: >- Одноразовый код отправлен по электронной почте для новой верификации (тарифицируется) value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Success reason: null vendor_data: user-1234 metadata: null Retry: summary: >- Повторная отправка в течение 5-минутного окна — новый код, тот же 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: один массив сообщений на каждое некорректное поле, вложенный в `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`. Также возвращается перед любой отправкой, если баланс организации не покрывает один кредит Email Verification API (`{"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: >- Превышен лимит запросов. Endpoint'ы POST/PATCH/DELETE делят общий лимит в 300 запросов на запись в минуту на один API-ключ (для создания транзакций и отправки событий действует отдельный лимит в 600). Ответ содержит заголовки `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` и `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Более 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: >- Сбой почтового провайдера после одной автоматической повторной попытки 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: >- `email_can_not_be_delivered`, когда `status` имеет значение `Undeliverable`; `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-ключ вашего приложения из раздела «Разработчикам» -> «API-ключи» в Business Console. Основной ключ имеет полный доступ. Именованный ключ может иметь ограниченную область действия: без доступа, чтение или запись для каждого ресурса, ограничение определенными сценариями или одобренными сессиями, списком IP-адресов и сроком действия. 401 означает, что ключ неверен, отозван или его срок действия истек; 403 означает, что ключ не был передан, у ключа нет доступа к этому ресурсу или действию, либо запрос поступил с адреса вне его списка IP-адресов; 404 на маршруте сессии означает, что сессия не входит в сценарии или статусы ключа. Ключ без доступа к медиа получает URL изображений, видео и PDF как null, а ключ без прав на запись сессий получает ссылки на сессии и токены как null. См. https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.