Como enviar SMS via API: guia prático passo a passo

Para enviar SMS via API são necessários três passos: criar uma conta em um provedor, trocar a sua chave de API por um token de acesso e fazer uma requisição POST com o número de destino e a mensagem. Na SMSGo, isso significa chamar GET /v1/auth/token com o header SMSGo-key e, em seguida, POST /v1/sms/send/single com o token no header Authorization: Bearer. O modelo é pré-pago, a partir de R$ 0,07 por SMS, sem mensalidade — e a conta nova já nasce com R$ 10 de créditos grátis, sem pedir cartão.

Por que enviar SMS por API ainda vale a pena

O SMS continua sendo o canal mais direto para alcançar uma pessoa: não depende de aplicativo instalado, de conexão de dados nem de aceite prévio em uma plataforma. Segundo a Gartner, mensagens SMS registram taxas de abertura de até 98% e de resposta de 45% — contra cerca de 20% e 6% do e-mail.

O alcance no Brasil é praticamente universal. Segundo dados da Anatel compilados pelo TELETIME, o país fechou 2025 com 270,2 milhões de linhas móveis em funcionamento, das quais 216,4 milhões são acessos humanos ativos — mais de uma linha por habitante.

E o volume corporativo segue crescendo: segundo a Juniper Research, o tráfego global de mensagens de negócios (A2P) deve sair de 2 trilhões de mensagens em 2025 para quase 3 trilhões até 2030. Integrar esse canal por API é o caminho padrão para quem envia códigos de verificação, alertas e notificações transacionais.

O que você precisa antes da primeira requisição

Uma conta ativa: o cadastro na SMSGo libera R$ 10 de créditos de cortesia, sem cartão de crédito.
Uma chave de API (SMSGo-key): disponível no painel, em Minha conta, na seção API. Trate-a como senha: variável de ambiente, nunca no código versionado.
Créditos pré-pagos: a partir de R$ 0,07 por SMS, sem mensalidade — e os créditos não expiram.

Passo 1: troque a chave por um token Bearer

A autenticação da SMSGo tem duas camadas. A chave de API nunca viaja nas chamadas de envio: você a troca por um token Bearer com validade de 48 horas no endpoint de autenticação.

curl -X GET https://api.smsgo.com.br/v1/auth/token \
  -H "SMSGo-key: SUA_CHAVE_AQUI"

# resposta:
# { "token": "oat_..." }

Guarde o token em cache e renove-o quando expirar. Se uma chamada retornar 401 unauthorized, basta repetir o passo acima e tentar de novo — é um bom candidato a interceptor no seu cliente HTTP.

Passo 2: envie o primeiro SMS

O envio individual usa POST /v1/sms/send/single, com o telefone no formato E.164 (DDI 55 + DDD + número) e a mensagem em texto puro:

curl -X POST https://api.smsgo.com.br/v1/sms/send/single \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+5511999990000", "message": "Seu codigo de acesso: 4821" }'

A resposta traz o essencial para o seu controle: { "id": "uuid", "quantity": 1, "segments": 1, "status": "queued" }. O id identifica o envio nas consultas e nos webhooks; segments é a quantidade de SMS efetivamente cobrados.

Exemplo em Node.js

const response = await fetch('https://api.smsgo.com.br/v1/sms/send/single', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.SMSGO_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone: '+5511999990000',
    message: 'Seu codigo de acesso: 4821',
  }),
})

const data = await response.json()
console.log(data.id, data.status, data.segments)

Exemplo em Python

import os
import requests

resp = requests.post(
    'https://api.smsgo.com.br/v1/sms/send/single',
    headers={'Authorization': 'Bearer ' + os.environ['SMSGO_TOKEN']},
    json={'phone': '+5511999990000', 'message': 'Seu codigo de acesso: 4821'},
)

print(resp.json())

Se preferir não montar as requisições na mão, há SDKs oficiais para as quatro linguagens mais comuns: @orynlabs/smsgo (npm) para Node.js, smsgo (PyPI) para Python, github.com/sms-go/smsgo-sdk-go para Go e orynlabs/smsgo (Packagist) para PHP.

Segmentos: como o tamanho da mensagem afeta o custo

Um SMS não comporta texto infinito. Mensagens em GSM-7 (texto simples, sem acentos) cabem em 160 caracteres; a partir daí, cada segmento adicional carrega 153. Se a mensagem contém acento, cedilha ou qualquer caractere fora do alfabeto GSM-7, a codificação muda para UTF-16/UCS-2 e o limite cai para 70 caracteres (67 por segmento adicional).

Cada segmento é um SMS cobrado — uma mensagem de 200 caracteres com acentos custa 3 segmentos, não 1. Antes de fechar o texto, valide no contador de caracteres de SMS quantos segmentos ele consome e considere remover acentos de mensagens transacionais para ficar no GSM-7.

Além do envio individual: endpoints que você vai usar

POST /v1/sms/send/multiple — envio em massa, com várias mensagens em uma única requisição.
GET /v1/sms/list — lista paginada dos envios da conta.
GET /v1/sms/{id}/show — detalhe de um envio específico.
GET /v1/sms/{id}/numbers — status individual por número em um envio em massa.
GET /v1/account/balance — saldo em reais, para monitorar antes de campanhas.
GET /v1/sms-types — catálogo de tipos de SMS e preços da sua conta.

Acompanhe a entrega com webhooks, não com polling

O status: "queued" da resposta é só o começo do ciclo de vida. Depois vêm os relatórios de entrega (DLR) da operadora: a mensagem foi entregue, falhou ou segue em trânsito. Consultar GET /v1/sms/{id}/show em loop funciona para depurar, mas não escala em produção.

O caminho correto é configurar um webhook com PUT /v1/account/webhook: a SMSGo passa a chamar a sua URL a cada mudança de status (evento sms.status) e a cada resposta do destinatário (evento sms.reply), com assinatura HMAC-SHA256 para você validar a origem. O passo a passo completo está em webhook de SMS na prática.

Boas práticas para produção

Normalize os números para E.164 antes de enviar; número mal formatado é a causa número um de falha de entrega.
Use o campo reference para amarrar cada envio ao seu domínio (ID do pedido, do usuário); ele é ecoado nos webhooks.
Trate os erros da API: 402 indica saldo insuficiente e 429 indica rate limit — respeite o header Retry-After antes de reenviar.
Respeite a LGPD em mensagens promocionais: só envie marketing com opt-in registrado e ofereça opt-out simples. Mensagens transacionais, como códigos de verificação, dispensam consentimento promocional. Os templates de SMS já vêm com opt-out onde é obrigatório.

Próximos passos

Se o seu caso de uso é login ou verificação de cadastro, siga para o guia de como enviar OTP por SMS, que cobre geração, expiração e validação do código de uso único. Para começar agora, crie sua conta na SMSGo: você ganha R$ 10 de créditos no cadastro, sem cartão, e dispara o primeiro SMS pela API em poucos minutos.