Guias
Códigos por e-mail
Pedir e validar códigos · piloto controlado
Piloto controlado
Esta API confirma o acesso a uma caixa de e-mail. O acesso real exige habilitação da conta e domínio de envio verificado. Os primeiros 60 envios OTP usam uma oferta única; depois, o volume pago de e-mail disponível. Não altera o OTP por SMS nem usa créditos SMS.
Usa uma chave API aprovada, no servidor, com permissão email. Não a exponhas no navegador nem na aplicação móvel.
1. Pedir o código
Substitui o UUID do domínio e o destinatário. Gera REQUEST_ID e um contexto aleatório de 32–200 caracteres no teu servidor; associa o contexto a este fluxo de confirmação e guarda-o até à validação.
curl https://api.kambasms.ao/email/otp/start \
-H "X-API-Key: $KAMBA_API_KEY" \
-H "Idempotency-Key: $REQUEST_ID" \
-H "Content-Type: application/json" \
-d '{
"to": "cliente@example.com",
"domain_id": "UUID_DO_DOMINIO_VERIFICADO",
"from_local": "verificacao",
"brand": "SUA_EMPRESA",
"context": "CONTEXTO_ALEATORIO_GUARDADO_NO_SERVIDOR",
"locale": "pt-AO"
}'A resposta 202 contém verification_id, expires_at e delivery_state. Guarda o ID. accepted significa aceitação pelo fornecedor, não entrega na caixa principal nem e-mail confirmado. uncertain exige consultar o pedido existente, nunca repetir às cegas com outra chave.
2. Validar o código
Usa o mesmo contexto e verification_id, com os seis dígitos introduzidos pelo utilizador. Apenas HTTP 200 com valid=true permite à tua aplicação marcar esse e-mail como confirmado neste fluxo.
curl https://api.kambasms.ao/email/otp/check \
-H "X-API-Key: $KAMBA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"verification_id": "UUID_DEVOLVIDO_NO_START",
"context": "CONTEXTO_ALEATORIO_GUARDADO_NO_SERVIDOR",
"code": "CODIGO_INTRODUZIDO_PELO_UTILIZADOR"
}'O código é de uso único, válido por 5 minutos e até 5 tentativas. A confirmação não prova identidade legal nem autoriza outra operação. Se o teu servidor perder a resposta de validação bem-sucedida, deve reconciliar a sua operação; a segunda validação devolve used.
Reenvio, limites e estado
Para novo código, chama start com outra Idempotency-Key e o mesmo contexto. Aguarda pelo menos 60 segundos. Limites: 3 pedidos por destinatário/hora e 100 por conta/ambiente/hora. O novo pedido cancela o código pendente anterior desse contexto.
Repetir a mesma chave e conteúdo devolve o pedido existente sem novo envio ou consumo. Conteúdo diferente devolve 409. A janela de repetição dura pelo menos até 24 horas após a expiração; não reutilizes chaves antigas para novas operações.
GET https://api.kambasms.ao/email/otp/VERIFICATION_ID
X-API-Key: $KAMBA_API_KEYO estado do desafio é apresentado separadamente de transport_status. Um e-mail entregue não implica código validado. Os webhooks de entrega Email existentes mantêm-se; esta versão não promete novos webhooks de OTP.
Os teus 60 e-mails OTP grátis
Oferta única por conta, atribuída no primeiro pedido real válido. Não renova mensalmente nem depende do domínio usado. O envio genérico de e-mail não a pode consumir. Cada novo envio aceite ou incerto reserva uma unidade; validar um código e repetir o mesmo pedido não consomem outra. Depois de esgotar a oferta, o envio exige volume pago; sem ele, a API devolve erro de quota.
GET /email/otp-trial consulta o estado da oferta sem atribuir ou alterar quota. Uma rejeição definitiva do fornecedor devolve a unidade; um timeout após possível aceitação não.
Sandbox
Usa uma chave kamba_test_ nas mesmas rotas, domain_id no formato UUID e os mesmos campos de validação. A Sandbox não contacta fornecedor nem consome volume. O test_code determinístico é 123456, devolvido apenas no ambiente de teste. IDs reais não podem ser validados na Sandbox.
Apresentação do e-mail
HTML e texto simples incluem um código de seis dígitos, validade e aviso de segurança. O Gmail pode apresentar o seu atalho para copiar; não é uma função garantida pela nossa API. Não é adicionado botão JavaScript ao e-mail.