@sendcloud-dev-br/js

SDK oficial do SendCloud para Node.js e browsers.

Instalação

npm install @sendcloud-dev-br/js
# ou
pnpm add @sendcloud-dev-br/js

Início rápido

import { SendCloud } from '@sendcloud-dev-br/js'

const sc = new SendCloud({ apiKey: process.env.SENDCLOUD_API_KEY! })

// Enviar um email
const { id } = await sc.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Bem-vindo!',
  html: '<h1>Olá! Seja bem-vindo.</h1>',
})

console.log('Email enfileirado:', id)

Referência

new SendCloud(config)

| Opção | Tipo | Descrição | |-------|------|-----------| | apiKey | string | Obrigatório. API Key gerada no dashboard. | | baseUrl | string | URL base da API. Padrão: https://api.sendcloud.dev.br |

sc.emails.send(payload)

Envia um email transacional.

await sc.emails.send({
  from: '[email protected]',
  to: '[email protected]',           // string ou string[] (até 50)
  subject: 'Redefinição de senha',
  html: '<p>Clique <a href="...">aqui</a> para redefinir.</p>',
  // Opcionais:
  text: 'Acesse: https://...',
  replyTo: '[email protected]',
  cc: ['[email protected]'],
  bcc: ['[email protected]'],
  tags: ['transacional', 'senha'],
  metadata: { userId: '123' },
  scheduledFor: '2026-06-01T10:00:00Z', // agendamento (máx 30 dias)
  idempotencyKey: 'reset-senha-user-123', // evita envio duplicado
})

sc.emails.send() com template

await sc.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  templateId: 'tpl_abc123',
  templateData: { nome: 'João', link: 'https://...' },
})

sc.emails.batch(payload)

Envia um template para múltiplos destinatários (máx 500). Cada um pode ter dados individuais.

await sc.emails.batch({
  from: '[email protected]',
  templateId: 'tpl_abc123',
  recipients: [
    { to: '[email protected]', templateData: { nome: 'João', pedido: '#001' } },
    { to: '[email protected]', templateData: { nome: 'Maria', pedido: '#002' } },
  ],
})

sc.emails.list(params?)

const { data, total } = await sc.emails.list({
  page: 1,
  limit: 20,
  status: 'delivered',
  search: 'joao@',
  from: '2026-05-01T00:00:00Z',
  to: '2026-05-31T23:59:59Z',
})

sc.emails.get(id)

const email = await sc.emails.get('em_abc123')
console.log(email.status, email.deliveredAt)

sc.emails.cancel(id)

Cancela um email agendado (somente status scheduled).

await sc.emails.cancel('em_abc123')

sc.emails.resend(id)

Reenvia um email já processado.

const { id } = await sc.emails.resend('em_abc123')

sc.templates.list()

const { data } = await sc.templates.list()

sc.templates.get(id)

const template = await sc.templates.get('tpl_abc123')

sc.templates.render(id, data)

Renderiza um template com dados de teste. Não envia nenhum email.

const { subject, html, text } = await sc.templates.render('tpl_abc123', {
  nome: 'João',
  link: 'https://exemplo.com',
})

sc.webhooks.verify(payload, signature, secret)

Verifica a assinatura HMAC-SHA256 de um webhook recebido.
Funciona em Node.js 18+, Deno, Edge (Vercel/Cloudflare) e browsers.

// Next.js App Router
export async function POST(req: Request) {
  const body = await req.text()
  const sig  = req.headers.get('x-sendcloud-signature') ?? ''

  const valid = await sc.webhooks.verify(body, sig, process.env.WEBHOOK_SECRET!)
  if (!valid) return new Response('Unauthorized', { status: 401 })

  const event = JSON.parse(body) // tipo WebhookEvent: { event, timestamp, data }
  console.log(event.event, event.data.emailId) // ex: "delivered", "abc123"

  return new Response('ok')
}

// Express (com body raw)
app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const valid = await sc.webhooks.verify(
    req.body,
    req.headers['x-sendcloud-signature'],
    process.env.WEBHOOK_SECRET!
  )
  if (!valid) return res.status(401).send('Invalid signature')

  const event = JSON.parse(req.body.toString())
  res.send('ok')
})

Tratamento de erros

Todos os erros da API lançam SendCloudError:

import { SendCloud, SendCloudError } from '@sendcloud-dev-br/js'

try {
  await sc.emails.send({ ... })
} catch (err) {
  if (err instanceof SendCloudError) {
    console.log(err.status) // HTTP status (400, 429, etc.)
    console.log(err.code)   // 'quota_exceeded', 'domain_not_found', ...
    console.log(err.message)
  }
}

Códigos de erro comuns

| Código | Status | Descrição | |--------|--------|-----------| | quota_exceeded | 429 | Limite mensal de emails atingido | | domain_not_found | 400 | Domínio remetente não cadastrado | | template_not_found | 400 | Template não encontrado | | recipient_suppressed | 422 | Destinatário na lista de supressão | | not_cancellable | 409 | Email não pode ser cancelado (já enviado) | | validation_error | 400 | Payload inválido |

Licença

MIT — SendCloud