> ## 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 de OTP por e-mail: enviar código de verificação > Envie um código de uso único por e-mail com POST /v3/email/send/ da Didit. Validade de 5 min, nova tentativa automática e pagamento por uso. ## OpenAPI ````yaml pt-br/openapi-25.json POST /v3/email/send/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificação de identidade. Autentique-se com o cabeçalho x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/email/send/: post: tags: - Standalone APIs summary: Enviar código por e-mail description: >- Envie uma senha de uso único (OTP) para um endereço de e-mail e depois verifique-a com [`POST /v3/email/check/`](/pt-br/standalone-apis/email-check). **Como o envio e a verificação se relacionam.** O estado da verificação é identificado pela sua aplicação mais o endereço `email`; a chamada de verificação não recebe `request_id`. Cada novo envio cria uma verificação pendente que dura **5 minutos**: chame a verificação com o mesmo endereço e o código que o usuário recebeu antes do fim desse prazo. Chamar o envio novamente para o mesmo endereço enquanto há uma verificação pendente gera um novo código para essa mesma verificação (`status: "Retry"`, mesmo `request_id`); o código anterior deixa de funcionar. No máximo uma nova tentativa é vinculada dessa forma (dois envios no total); um envio seguinte inicia uma nova verificação com um novo `request_id`. O prazo de 5 minutos é contado a partir do primeiro envio e não é estendido por novas tentativas. **Pré-verificação de entregabilidade.** Antes de qualquer envio, o endereço passa por validação de sintaxe e de DNS/MX. Endereços que não podem receber e-mails retornam `200` com `status: "Undeliverable"` e `reason: "email_can_not_be_delivered"`: nenhum e-mail é enviado, nada é cobrado e a verificação é finalizada imediatamente como `Declined` (uma verificação posterior retorna `Expired or Not Found`). Uma falha de envio downstream é informada da mesma forma. **Formato do código e identidade visual.** Os códigos têm de 4 a 8 caracteres (`options.code_size`, padrão 6) e são numéricos por padrão; defina `options.alphanumeric_code: true` para usar letras maiúsculas e dígitos (a comparação na verificação não diferencia maiúsculas de minúsculas). O modelo de e-mail é localizado via `options.locale` (54 idiomas compatíveis) e pode usar a identidade visual de marca própria da sua aplicação via `options.use_white_label_customization`. **Faturamento.** Um crédito da API de Verificação de e-mail por envio bem-sucedido (`status: "Success"`), cobrado no momento do envio. Envios `Retry` e `Undeliverable` são gratuitos, assim como as verificações. **Persistência da sessão.** Toda nova verificação é salva como uma sessão do tipo API: `request_id` é um ID de sessão real que você pode passar para `GET /v3/session/{sessionId}/decision/`, a verificação aparece no Business Console e webhooks `status.updated` são disparados conforme ela avança. **Sandbox.** Chaves de API de sandbox ignoram a entrega e o faturamento: após a validação da requisição (entradas malformadas ainda retornam `400`), o endpoint retorna um payload estático `Success` com um `request_id` aleatório; nenhum e-mail é enviado e nada é salvo. Use o código `123456` na verificação em sandbox. **Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais ausentes ou inválidas retornam `403` (`{"detail": "You do not have permission to perform this action."}`); esta API nunca retorna `401`. **Limite de requisições.** Cota de escrita compartilhada de 300 requisições/min por chave de API em todos os endpoints POST/PATCH/DELETE; ultrapassá-la retorna `429`. operationId: post_v3email_send requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email description: >- Endereço de e-mail do destinatário. Endereços malformados retornam `400`; endereços sintaticamente válidos que não podem receber e-mails (falha na validação de DNS/MX) retornam `200` com `status: "Undeliverable"`. example: alice@example.com options: type: object description: >- Opções de formato, localização e identidade visual do OTP. Todos os campos são opcionais. properties: code_size: type: integer minimum: 4 maximum: 8 default: 6 description: >- Número de caracteres do OTP (dígitos por padrão; letras maiúsculas e dígitos quando `alphanumeric_code` é `true`). alphanumeric_code: type: boolean default: false description: >- Quando `true`, o OTP é composto por letras maiúsculas `A–Z` e dígitos `0–9`, em vez de apenas dígitos. A comparação em `/v3/email/check/` não diferencia maiúsculas de minúsculas. 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 do modelo de e-mail do OTP. O padrão é `en`. Valores não suportados retornam `400` com a lista de todos os locales suportados. example: en use_white_label_customization: type: boolean default: false description: >- Quando `true`, o e-mail de OTP usa a personalização de marca própria da sua aplicação (logotipo, cores, identidade do remetente) em vez do modelo padrão da Didit. signals: type: object description: >- Sinais opcionais de dispositivo e rede sobre o usuário final, encaminhados à camada antifraude para melhorar a detecção de tráfego abusivo ou automatizado. Todos os campos são opcionais. properties: ip: type: string description: >- Endereço IP do dispositivo do usuário final. IPv4 ou IPv6. example: 192.0.2.1 device_id: type: string maxLength: 255 description: >- Identificador único do dispositivo do usuário final. Android: `ANDROID_ID`; iOS: `identifierForVendor`. example: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: type: string enum: - android - ios - ipados - tvos - web description: Plataforma do dispositivo do usuário final. device_model: type: string maxLength: 255 description: Modelo do dispositivo do usuário final. example: iPhone17,2 os_version: type: string maxLength: 64 description: >- Versão do sistema operacional do dispositivo do usuário final. example: 18.0.1 app_version: type: string maxLength: 64 description: Versão da sua aplicação. example: 1.2.34 user_agent: type: string maxLength: 512 description: User agent do navegador ou app do usuário 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 controlado por quem faz a chamada (seu id interno de usuário, um e-mail, um UUID etc.), persistido na sessão e devolvido na resposta do envio, na resposta da verificação correspondente, nos webhooks e no Business Console. Use-o para correlacionar o `request_id` da Didit com o registro do seu usuário. metadata: type: object nullable: true description: >- Objeto JSON livre e opcional, persistido na sessão e devolvido na resposta de envio, na resposta da verificação correspondente, nos webhooks e no Business Console. required: - email examples: Numeric 6-digit code: summary: 'Padrão: código numérico de 6 dígitos em inglês' value: email: alice@example.com options: locale: en vendor_data: user-1234 Alphanumeric 8-character code: summary: Letras maiúsculas + dígitos, modelo espanhol value: email: bob@example.com options: code_size: 8 alphanumeric_code: true locale: es White-label branding: summary: >- Enviar o e-mail de OTP com a personalização de marca própria da sua aplicação value: email: carol@example.com options: locale: en use_white_label_customization: true vendor_data: user-5678 responses: '200': description: >- Envio confirmado. Verifique `status`: `Success` e `Retry` significam que um código está a caminho; `Undeliverable` significa que o endereço não pode receber e-mails e a verificação já foi finalizada como `Declined`. `request_id` é o id da sessão persistida (o mesmo id em um `Retry`). content: application/json: schema: $ref: '#/components/schemas/EmailVerificationSendResponse' examples: Success: summary: OTP enviado por e-mail para uma nova verificação (cobrado) value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Success reason: null vendor_data: user-1234 metadata: null Retry: summary: >- Segundo envio dentro da janela de 5 minutos — novo código, mesmo request_id, gratuito value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Retry reason: null vendor_data: user-1234 metadata: null Undeliverable: summary: >- O endereço falhou na validação de DNS/MX: verificação finalizada como Recusada, nada cobrado value: request_id: cb1a5011-344d-444d-bdce-218904745d7f status: Undeliverable reason: email_can_not_be_delivered vendor_data: user-1234 metadata: null '400': description: >- Erro de validação: envelope de erros de campo do DRF, com um array de mensagens por campo com problema, aninhado em `options` para erros de opção. content: application/json: examples: Invalid email: summary: Endereço de e-mail com formato inválido value: email: - Enter a valid email address. Unsupported locale: summary: '`options.locale` fora do conjunto suportado' 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 do intervalo 4–8' value: options: code_size: - Ensure this value is less than or equal to 8. '403': description: >- Permissão negada. Retornado quando o cabeçalho `x-api-key` está ausente (`{"detail": ...}`); uma chave incorreta, revogada ou expirada retorna `401`. Também é retornado antes de qualquer envio quando o saldo da organização não cobre um crédito da API de Verificação de e-mail (`{"error": ...}`). content: application/json: examples: Missing or invalid API key: summary: Nenhum cabeçalho `x-api-key`, ou a chave é inválida/revogada value: detail: You do not have permission to perform this action. Not enough credits: summary: O saldo da organização não cobre o preço do envio value: error: You don't have enough credits to perform this request. '429': description: >- Limite de requisições excedido. Todos os endpoints POST/PATCH/DELETE compartilham uma cota de 300 requisições de escrita por minuto por chave de API. A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Mais de 300 requisições de escrita no minuto atual 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: >- Não foi possível acessar o provedor de e-mail (uma indisponibilidade ou um tempo limite esgotado), então nenhum código foi enviado e nada foi cobrado nem contado como tentativa de envio. Repita a mesma requisição. content: application/json: examples: Email delivery unavailable: summary: >- O provedor de e-mail falhou após uma nova tentativa automática 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 da sessão da verificação. Um envio `Retry` retorna o mesmo `request_id` do envio original. Este ID aparece no Business Console, é retornado novamente por um `POST /v3/email/check/` finalizado e pode ser passado para `GET /v3/session/{sessionId}/decision/`. status: type: string enum: - Success - Retry - Undeliverable description: >- `Success`: OTP enviado por e-mail para uma nova verificação (cobrado). `Retry`: novo OTP enviado por e-mail para a verificação pendente criada por um envio anterior (gratuito). `Undeliverable`: o endereço não passou na validação de entregabilidade ou não foi possível enviar a mensagem; a verificação é finalizada imediatamente como `Declined` e nada é cobrado. reason: type: string nullable: true enum: - email_can_not_be_delivered - null description: >- `email_can_not_be_delivered` quando `status` é `Undeliverable`; `null` nos demais casos. vendor_data: type: string nullable: true description: Eco do `vendor_data` armazenado na sessão (do primeiro envio). metadata: type: object nullable: true description: Eco do `metadata` armazenado na sessão (do primeiro envio). securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está errada, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.