> ## 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 para enviar OTP por e-mail: código de verificação > Envie códigos OTP por e-mail com a API da Didit (POST /v3/email/send/). Nova tentativa automática, validade de 5 min, sem mínimos mensais. ## OpenAPI ````yaml pt/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 um código de utilização única (OTP) para um endereço de e-mail e, em seguida, verifique-o com [`POST /v3/email/check/`](/pt/standalone-apis/email-check). **Como funcionam o envio e a verificação em conjunto.** O estado da verificação é indexado 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 utilizador recebeu antes do fecho da janela temporal. Chamar o envio novamente para o mesmo endereço enquanto uma verificação está pendente gera um novo código para essa mesma verificação (`status: "Retry"`, mesmo `request_id`); o código anterior deixa de funcionar. É associada no máximo uma nova tentativa desta forma (dois envios no total); um envio adicional inicia uma nova verificação com um novo `request_id`. A janela de 5 minutos é contabilizada a partir do primeiro envio e não é prolongada por novas tentativas. **Pré-verificação de capacidade de entrega.** Antes de qualquer envio, o endereço passa por validação de sintaxe e de DNS/MX. Os endereços que não conseguem receber mensagens devolvem `200` com `status: "Undeliverable"` e `reason: "email_can_not_be_delivered"` — nenhum e-mail é enviado, nada é faturado e a verificação é imediatamente finalizada como `Declined` (uma verificação posterior devolve `Expired or Not Found`). Um envio que falhe por um motivo que não seja o endereço (o e-mail não pôde ser entregue para envio) devolve `503`: nenhum código é enviado, nada é faturado, a verificação permanece aberta e o mesmo pedido pode ser repetido. **Formato do código e personalização.** Os códigos têm entre 4 e 8 carateres (`options.code_size`, por omissão 6), numéricos por predefinição; defina `options.alphanumeric_code: true` para 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 através de `options.locale` (54 idiomas suportados) e pode utilizar a personalização de marca branca da sua aplicação através de `options.use_white_label_customization`. **Faturação.** Um crédito da API de Verificação de e-mail por envio bem-sucedido (`status: "Success"`), cobrado no momento do envio. Os envios `Retry` e `Undeliverable` são gratuitos, e as verificações são gratuitas. **Persistência da sessão.** Cada nova verificação é persistida como uma sessão do tipo API: `request_id` é um ID de sessão real que pode passar a `GET /v3/session/{sessionId}/decision/`, a verificação aparece na Business Console e os webhooks `status.updated` são acionados à medida que progride. **Sandbox.** As chaves de API de sandbox ignoram a entrega e a faturação: após a validação do pedido (dados malformados continuam a devolver `400`), o endpoint devolve um payload estático `Success` com um `request_id` aleatório; nenhum e-mail é enviado e nada é persistido. Utilize 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 em falta ou inválidas devolvem `403` (`{"detail": "You do not have permission to perform this action."}`) — esta API nunca devolve `401`. **Limite de pedidos.** Limite partilhado de escrita de 300 pedidos/min por chave de API em todos os endpoints POST/PATCH/DELETE; excedê-lo devolve `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 devolvem `400`; endereços sintaticamente válidos que não conseguem receber correio (falha na validação de DNS/MX) devolvem `200` com `status: "Undeliverable"`. example: alice@example.com options: type: object description: >- Opções de formato, localização e personalização de marca do OTP. Todos os campos são opcionais. properties: code_size: type: integer minimum: 4 maximum: 8 default: 6 description: >- Número de carateres no OTP (dígitos por predefinição; letras maiúsculas e dígitos quando `alphanumeric_code` for `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 de `/v3/email/check/` não faz distinção entre maiúsculas e 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 de OTP. A predefinição é `en`. Valores não suportados devolvem `400`, que lista todas as configurações regionais suportadas. example: en use_white_label_customization: type: boolean default: false description: >- Quando `true`, o e-mail com OTP utiliza a personalização de marca branca da sua aplicação (logótipo, cores, marca do remetente) em vez do modelo predefinido da Didit. signals: type: object description: >- Sinais opcionais de dispositivo e rede sobre o utilizador final, encaminhados para a camada antifraude para melhorar a deteção de tráfego abusivo ou automatizado. Todos os campos são opcionais. properties: ip: type: string description: >- Endereço IP do dispositivo do utilizador final. IPv4 ou IPv6. example: 192.0.2.1 device_id: type: string maxLength: 255 description: >- Identificador único do dispositivo do utilizador 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 utilizador final. device_model: type: string maxLength: 255 description: Modelo do dispositivo do utilizador final. example: iPhone17,2 os_version: type: string maxLength: 64 description: >- Versão do sistema operativo do dispositivo do utilizador 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: >- Agente do utilizador do navegador ou da aplicação do utilizador 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 pelo chamador (o seu ID de utilizador interno, um e-mail, um UUID, etc.) guardado na sessão e devolvido na resposta de envio, na resposta de verificação de correspondência, nos webhooks e na Business Console. Utilize-o para correlacionar o `request_id` da Didit com o registo do seu utilizador. metadata: type: object nullable: true description: >- Objeto JSON de formato livre opcional persistido na sessão e devolvido na resposta de envio, na resposta de verificação de correspondência, nos webhooks e na Business Console. required: - email examples: Numeric 6-digit code: summary: Predefiniçã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: >- Envie o e-mail com OTP com a personalização de marca branca 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. Inspecione `status`: `Success` e `Retry` significam que um código está a caminho; `Undeliverable` significa que a morada não pode receber correio e a verificação já foi finalizada como `Declined`. `request_id` é o ID persistido da sessão (o mesmo ID num `Retry`). content: application/json: schema: $ref: '#/components/schemas/EmailVerificationSendResponse' examples: Success: summary: OTP enviado por e-mail para uma nova verificação (faturado) 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 — código novo, 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 a validação de DNS/MX — verificação finalizada como Recusada, sem qualquer faturação 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 erro de campo do DRF: um array de mensagens por campo com problemas, aninhado sob `options` para erros de opções. content: application/json: examples: Invalid email: summary: Endereço de e-mail mal formatado 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. Devolvido quando o cabeçalho `x-api-key` está em falta (`{"detail": ...}`); uma chave incorreta, revogada ou expirada devolve `401`. Também é devolvido antes de qualquer envio quando o saldo da organização não consegue cobrir um crédito da API de Verificação de e-mail (`{"error": ...}`). content: application/json: examples: Missing or invalid API key: summary: Sem 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 de envio value: error: You don't have enough credits to perform this request. '429': description: >- Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). 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 pedidos 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 enviar o e-mail por um motivo não relacionado com o endereço (não foi possível contactar o fornecedor de e-mail, o tempo limite expirou ou este recusou o próprio envio), pelo que nenhum código foi enviado e nada foi faturado ou contabilizado como tentativa de envio. Repita o mesmo pedido. content: application/json: examples: Email delivery unavailable: summary: >- O fornecedor 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 de sessão da verificação. Um envio de `Retry` devolve o mesmo `request_id` que o envio original. Este id surge na Business Console, é devolvido 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 (faturado). `Retry` — novo OTP enviado por e-mail para a verificação pendente criada por um envio anterior (gratuito). `Undeliverable` — o endereço falhou a validação de capacidade de entrega ou a mensagem não pôde ser enviada; a verificação é imediatamente finalizada como `Declined` e nada é faturado. reason: type: string nullable: true enum: - email_can_not_be_delivered - null description: >- `email_can_not_be_delivered` quando `status` é `Undeliverable`; `null` caso contrário. vendor_data: type: string nullable: true description: >- Eco do objeto `vendor_data` armazenado na sessão (do primeiro envio). metadata: type: object nullable: true description: Eco do objeto `metadata` armazenado na sessão (do primeiro envio). securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, 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á incorreta, 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 o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.