smskitdocs

SMS

Envie, consulte e liste envios, com a situação de cada destinatário.

Base https://api.smskit.dev · Autorização Bearer <token> · como obter o token

POST/v1/sms

Enviar SMS

Aceita um ou vários destinatários (to), com text livre ou template + variables. Texto livre não exige modelo aprovado, mas passa pelas mesmas validações do console. O texto final — incluindo from e os valores das variáveis — tem no máximo 160 caracteres e aceita apenas letras sem acento, números, espaço, quebra de linha e pontuação: acentos e emojis chegam embaralhados no aparelho e são recusados com 422 validation_error antes de qualquer cobrança. Todo envio passa por análise de risco (spam, golpe, phishing, links). Risco baixo entra na fila (queued) e responde 202. Risco médio ou alto responde 409 review_required sem cobrar nada, com o que ajustar em details: corrija o texto, use um modelo aprovado ou repita com accept_review: true para aceitar a revisão manual (review), que reserva os créditos até a decisão. Um envio que usa modelo aprovado nunca pede essa confirmação. Envios em produção exigem o cadastro do titular concluído no console (identity_required). A entrega chega por webhook ou por GET /v1/sms/{id}. Envie Idempotency-Key para repetir com segurança.

Parâmetros

idempotency-keystringheader

Corpo · SendRequest

accept_reviewboolean
Aceita que o envio espere por revisão manual quando a análise automática não aprovar o texto. Sem isso, um texto que seria retido responde 409 review_required e nada é cobrado.
fromstring | null
até 40 caracteres
kindauthentication | utility | null
Which delivery route a message takes.valores: authentication, utility
metadataobject<string> | null
scheduled_atdate-time | null
templatestring | null
até 100 caracteres
textstring | null
até 1000 caracteres
tostring | string[]obrigatório
variablesobject<string> | null

Respostas

  • 202Objeto SmsOutcompleted_at, created_at, credits, from, id, kind, messages, metadata, object, recipients, scheduled_at, segments, status, template, test, text
  • 401Credencial ausente, inválida ou expirada
  • 402insufficient_balance
  • 403template_not_approved ou identity_required
  • 409review_required (a análise não aprovou o texto) ou conflict (Idempotency-Key reutilizada com outro corpo)
  • 422validation_error
  • 429rate_limited — respeite Retry-After
curl -X POST https://api.smskit.dev/v1/sms \
  -H "Authorization: Bearer $SMSKIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511999990123",
    "from": "Studio",
    "text": "Seu pedido saiu para entrega. Chega em 30 minutos."
  }'
202 · resposta
{
  "id": "sms_7f3k2m",
  "object": "sms",
  "from": "Studio",
  "text": "Seu pedido saiu para entrega. Chega em 30 minutos.",
  "template": "order-confirmed",
  "status": "queued",
  "created_at": "2026-09-11T14:03:00Z",
  "credits": 1,
  "kind": "utility",
  "recipients": 1,
  "segments": 1,
  "test": false,
  "completed_at": null,
  "messages": [
    {
      "id": "msg_2b9x4c",
      "object": "message",
      "to": "+5511999990123",
      "status": "queued",
      "updated_at": "2026-09-11T14:03:05Z",
      "error": null
    }
  ],
  "metadata": {
    "order_id": "1042"
  },
  "scheduled_at": null
}

GET/v1/sms

Listar envios

Parâmetros

limitintegerquery
padrão: 20
starting_afterstringquery

Respostas

  • 200Objeto SmsListdata, has_more, next_cursor, object
  • 401Credencial ausente, inválida ou expirada
  • 422validation_error
  • 429rate_limited — respeite Retry-After
curl https://api.smskit.dev/v1/sms?limit=20 \
  -H "Authorization: Bearer $SMSKIT_TOKEN"
200 · resposta
{
  "object": "list",
  "data": [
    {
      "id": "sms_7f3k2m",
      "object": "sms",
      "from": "Studio",
      "text": "Seu pedido saiu para entrega. Chega em 30 minutos.",
      "template": "order-confirmed",
      "status": "queued",
      "created_at": "2026-09-11T14:03:00Z",
      "credits": 1,
      "kind": "utility",
      "recipients": 1,
      "segments": 1,
      "test": false,
      "completed_at": null,
      "messages": [
        {
          "id": "msg_2b9x4c",
          "object": "message",
          "to": "+5511999990123",
          "status": "queued",
          "updated_at": "2026-09-11T14:03:05Z",
          "error": null
        }
      ],
      "metadata": {
        "order_id": "1042"
      },
      "scheduled_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/v1/sms/{sms_id}

Consultar um envio e seus destinatários

Parâmetros

sms_idstringobrigatório

Respostas

  • 200Objeto SmsOutcompleted_at, created_at, credits, from, id, kind, messages, metadata, object, recipients, scheduled_at, segments, status, template, test, text
  • 401Credencial ausente, inválida ou expirada
  • 404not_found
  • 422validation_error
  • 429rate_limited — respeite Retry-After
curl https://api.smskit.dev/v1/sms/sms_7f3k2m \
  -H "Authorization: Bearer $SMSKIT_TOKEN"
200 · resposta
{
  "id": "sms_7f3k2m",
  "object": "sms",
  "from": "Studio",
  "text": "Seu pedido saiu para entrega. Chega em 30 minutos.",
  "template": "order-confirmed",
  "status": "queued",
  "created_at": "2026-09-11T14:03:00Z",
  "credits": 1,
  "kind": "utility",
  "recipients": 1,
  "segments": 1,
  "test": false,
  "completed_at": null,
  "messages": [
    {
      "id": "msg_2b9x4c",
      "object": "message",
      "to": "+5511999990123",
      "status": "queued",
      "updated_at": "2026-09-11T14:03:05Z",
      "error": null
    }
  ],
  "metadata": {
    "order_id": "1042"
  },
  "scheduled_at": null
}