Conceitos
Entrega e estados
Uma resposta 202 registra o envio na fila. O processamento escolhe o remetente, envia a mensagem e atualiza os estados conforme os recibos disponíveis.
Nesta página
Canais disponíveis
| Canal | Disponibilidade na API pública |
|---|---|
| Entrega real em live, usando remetentes disponíveis da plataforma. | |
| Sandbox | Simulação em test, sem mensagem real. |
422 channel_unavailable, mesmo com um endereço válido. | |
| SMS | Ainda não disponível no fluxo público de OTP. |
| Telegram | Ainda não disponível no fluxo público de OTP. |
Ter SMTP ou testes de SMS configuráveis no painel não habilita esses canais em POST /v1/send. O cliente não escolhe o canal com um campo no corpo.
Estados de entrega: status
| Estado | Significado |
|---|---|
queued | Envio aceito; aguardando processamento ou um remetente disponível. |
sending | Envio roteado para uma tentativa de entrega. |
sent | O provedor aceitou a mensagem. Ainda não confirma que chegou ao telefone. |
delivered | O provedor confirmou a entrega. |
read | O provedor confirmou a leitura. |
failed | A entrega encerrou com falha. Consulte failure_reason. |
Recibos podem chegar com atraso ou não chegar. Um envio pode permanecer em sent, e nem toda integração verá todos os estados intermediários.
Em teste, o processamento simula sent, delivered e read de uma vez, com channel: sandbox.
Estados do código: verification
| Estado | Significado |
|---|---|
pending | Código ainda pode ser verificado dentro do prazo. |
verified | O código já foi usado com sucesso. |
expired | O prazo de um código pendente encerrou. |
locked | Cinco verificações incorretas bloquearam o envio. |
A entrega e a verificação são independentes. Uma mensagem lida pode estar pendente, e uma mensagem entregue pode ter um código expirado. Use valid: true na verificação para autenticar.
Falhas de entrega
| failure_reason | Significado |
|---|---|
expired_before_delivery | O código expirou antes de a entrega terminar. |
attempts_exhausted | O processamento esgotou as tentativas de entrega. |
rejected_by_provider | O provedor rejeitou a mensagem. |
Enquanto não houver remetente disponível, o envio pode continuar queued até expirar. O processamento faz as retentativas de entrega; não crie envios repetidos a cada consulta de status.
Quando a entrega falha de forma definitiva, a plataforma devolve a unidade reservada da cota grátis ou o crédito. Veja reserva e devolução.