comms

O seu código nomeia um template e um idioma. Qual provedor carrega isso, e o que a mensagem de fato diz, são configuração — então mudar qualquer um dos dois não é um deploy.

email.send

email.send(params) → null

const { data, error } = await nulvless.comms.email.send({
  to: '[email protected]',
  template: 'grants-invite',
  language: 'pt-BR',
  params: { organization: 'Acme Inc', role: 'admin' },
});

sms.send

sms.send(params) → null

O mesmo formato, com phone no lugar de to.

await nulvless.comms.sms.send({
  phone: { country_code: '+55', number: '11987654321' },
  template: 'phone-otp-verification',
  language: 'en-US',
  params: { code: '492013' },
});

Envios têm cota por canal. Esgotá-la responde 429 rate_limit_exceeded — sem retryAfter, diferente do serviço de auth, então mantenha o seu próprio backoff.

email.test e sms.test

test(recipient) → null

Envia uma sonda para você confirmar que o provedor está ligado antes de uma mensagem real depender disso.

await nulvless.comms.email.test('[email protected]');

Vale rodar do seu pipeline de deploy contra um ambiente novo — um provedor mal configurado é invisível até a primeira pessoa precisar de um código de verificação.

Templates que já vêm prontos

Todo ambiente começa com os templates de que a própria plataforma precisa. Estes são os slugs, e cada um é editável:

Um template é por canal: as versões de e-mail e SMS da mesma ideia são slugs separados, porque um texto que funciona numa caixa de entrada não sobrevive a 160 caracteres.

templates

list · get · create · update · delete

await nulvless.comms.templates.list({ channel: 'email' });
await nulvless.comms.templates.get('email', 'welcome-user', 'pt-BR');
await nulvless.comms.templates.create(params);
await nulvless.comms.templates.update('email', 'welcome-user', params, 'pt-BR');
await nulvless.comms.templates.delete('email', 'welcome-user', 'pt-BR');

Tudo exceto create e list é endereçado por canal + slug + idioma. Essa tripla é a identidade de um template — não há id para guardar, e o mesmo slug em dois idiomas são dois registros.

A maioria dos times edita isso no console. A API existe para quando você versiona os templates junto com a aplicação.

create

O update recebe os mesmos campos opcionais menos slug, channel e language — esses identificam o template em vez de descrevê-lo.

O canal de webhook

Além de e-mail e SMS, um template pode ser um webhook: em vez de renderizar uma mensagem para uma pessoa, ele posta numa url sua. O ponto de chamada é idêntico — mesmo slug, mesmos params — então uma notificação pode migrar de e-mail para webhook por configuração, sem tocar no código que dispara.

O objeto Template

Por que nomear um template

Nomear um template em vez de compor uma mensagem é o que faz o resto funcionar:

• Por idioma — a mesma chamada renderiza pt-BR ou en-US a partir de um slug.
• Por ambiente — desenvolvimento aponta para um provedor de sandbox, então um teste nunca chega numa caixa de entrada real.
• Por canal — as versões de e-mail e SMS de uma mensagem são editadas lado a lado.

Nada disso exige que o código que chama mude.

Próximos