Documentação da API

Referência completa para integrar o SendCloud na sua aplicação.

Quick Start

1Crie uma conta grátis e adicione seu domínio em Domínios.
2Gere uma API Key em API Keys no painel.
3Envie seu primeiro email com uma requisição POST /v1/emails/send.

Exemplo

curl -X POST https://api.sendcloud.dev.br/v1/emails/send \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "destinatario@exemplo.com",
    "from": "noreply@seudominio.com",
    "subject": "Olá do SendCloud!",
    "html": "<h1>Funcionou!</h1>"
  }'

Autenticação

URL base

https://api.sendcloud.dev.br

Todas as requisições precisam do header Authorization: Bearer <API_KEY>. Gere sua chave no painel após criar uma conta.

POST/v1/emails/send

Enviar email

Enfileira um email para envio imediato.

Campo	Tipo	Req.	Descrição
to	string \| string[]	sim	Email(s) do(s) destinatário(s) — aceita string única ou array de até 50 endereços
from	string	sim	Email do remetente (domínio deve estar cadastrado)
subject	string	sim	Assunto do email
html	string	não	Corpo HTML. Obrigatório se templateId não for informado
templateId	string	não	ID de um template salvo (substitui html)
templateData	object	não	Variáveis para substituição no template Handlebars
replyTo	string	não	Email para Reply-To
cc	string[]	não	Cópia
bcc	string[]	não	Cópia oculta
tags	string[]	não	Tags para filtrar emails
metadata	object	não	Dados adicionais para rastreamento
attachments	object[]	não	Anexos. Cada item: { filename, content (base64), contentType? }. Máx 10 arquivos, 10 MB total.
scheduledFor	string	não	ISO 8601: data/hora futura para envio agendado (máx 30 dias). Retorna status "scheduled" em vez de "queued".
idempotencyKey	string	não	Chave única por workspace (máx 255 chars). Retorna o email original se a chave já foi usada, sem reenviar. Útil para retentativas seguras.

Request body

json

{
  "to": "destinatario@exemplo.com",
  "from": "noreply@seudominio.com",
  "subject": "Assunto do email",
  "html": "<h1>Olá!</h1><p>Corpo do email.</p>",
  "attachments": [
    {
      "filename": "fatura.pdf",
      "content": "<base64>",
      "contentType": "application/pdf"
    }
  ]
}

Response

json

{
  "id": "clxyz123...",
  "status": "queued",
  "createdAt": "2026-01-01T12:00:00.000Z"
}

Exemplo

curl -X POST https://api.sendcloud.dev.br/v1/emails/send \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "destinatario@exemplo.com",
    "from": "noreply@seudominio.com",
    "subject": "Assunto do email",
    "html": "<h1>Olá!</h1>"
  }'

GET/v1/emails

Listar emails

Retorna o histórico de emails com paginação, filtro por status e busca por destinatário ou assunto.

Campo	Tipo	Req.	Descrição
page	number	não	Página (padrão: 1)
limit	number	não	Itens por página, máx 100 (padrão: 20)
status	string	não	queued \| sent \| delivered \| bounced \| failed \| opened \| clicked
search	string	não	Busca por destinatário (to) ou assunto (subject)

Response

json

{
  "data": [
    {
      "id": "clxyz123...",
      "to": "dest@exemplo.com",
      "from": "noreply@seudominio.com",
      "subject": "Assunto",
      "status": "delivered",
      "createdAt": "2026-01-01T12:00:00.000Z",
      "sentAt": "2026-01-01T12:00:01.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

Exemplo

curl "https://api.sendcloud.dev.br/v1/emails?page=1&limit=20&status=delivered&search=joao" \
  -H "Authorization: Bearer SUA_API_KEY"

GET/v1/emails/:id

Detalhe do email

Retorna todos os dados de um email, incluindo HTML e status de entrega.

Response

json

{
  "id": "clxyz123...",
  "to": "dest@exemplo.com",
  "from": "noreply@seudominio.com",
  "subject": "Assunto",
  "status": "delivered",
  "htmlContent": "<h1>...</h1>",
  "createdAt": "2026-01-01T12:00:00.000Z",
  "sentAt": "2026-01-01T12:00:01.000Z",
  "deliveredAt": "2026-01-01T12:00:05.000Z",
  "errorMessage": null,
  "tags": [],
  "retryCount": 0,
  "replyTo": null,
  "cc": [],
  "bcc": [],
  "metadata": null
}

Exemplo

curl "https://api.sendcloud.dev.br/v1/emails/EMAIL_ID" \
  -H "Authorization: Bearer SUA_API_KEY"

GET/v1/emails/:id/events

Linha do tempo do email

Retorna os eventos de ciclo de vida de um email em ordem cronológica.

Response

json

{
  "data": [
    {
      "id": "evt_abc...",
      "eventType": "delivered",
      "createdAt": "2026-01-01T12:00:05.000Z",
      "sentToWebhook": true,
      "payload": { "emailId": "clxyz123...", "to": "dest@exemplo.com" }
    },
    {
      "id": "evt_def...",
      "eventType": "opened",
      "createdAt": "2026-01-01T12:05:00.000Z",
      "sentToWebhook": true,
      "payload": { "emailId": "clxyz123..." }
    }
  ]
}

Exemplo

curl "https://api.sendcloud.dev.br/v1/emails/EMAIL_ID/events" \
  -H "Authorization: Bearer SUA_API_KEY"

GET/v1/emails/export

Exportar emails para CSV

Retorna um arquivo CSV com até 10.000 emails, respeitando os filtros informados.

Campo	Tipo	Req.	Descrição
status	string	não	Filtro por status
search	string	não	Busca por destinatário ou assunto
from	string	não	Data de início em ISO 8601
to	string	não	Data de fim em ISO 8601

Exemplo

curl "https://api.sendcloud.dev.br/v1/emails/export?status=bounced" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -o emails.csv

POST/v1/emails/:id/resend

Reenviar email

Cria uma cópia do email e enfileira para reenvio imediato. Consome quota mensal normalmente.

Response

json

{
  "id": "clxyz456...",
  "status": "queued",
  "createdAt": "2026-01-02T10:00:00.000Z"
}

Exemplo

curl -X POST "https://api.sendcloud.dev.br/v1/emails/EMAIL_ID/resend" \
  -H "Authorization: Bearer SUA_API_KEY"

DELETE/v1/emails/:id

Cancelar email agendado

Cancela um email com status scheduled antes do envio. Retorna erro 409 se o email já foi enviado.

Response

json

{
  "id": "clxyz123...",
  "status": "cancelled"
}

Exemplo

curl -X DELETE "https://api.sendcloud.dev.br/v1/emails/EMAIL_ID" \
  -H "Authorization: Bearer SUA_API_KEY"

POST/v1/emails/batch

Envio em lote (batch)

Envia um template para até 500 destinatários em uma única requisição. Cada destinatário recebe sua própria cópia com templateData individual.

Campo	Tipo	Req.	Descrição
from	string	sim	Email do remetente (domínio deve estar cadastrado)
templateId	string	sim	ID do template Handlebars
recipients	object[]	sim	Array de destinatários (máx 500). Cada item: { to: string, templateData?: object }

Request body

json

{
  "from": "noreply@seudominio.com",
  "templateId": "tpl_abc123...",
  "recipients": [
    { "to": "joao@exemplo.com", "templateData": { "name": "João" } },
    { "to": "maria@exemplo.com", "templateData": { "name": "Maria" } }
  ]
}

Response

json

{
  "queued": 2,
  "ids": ["clxyz100...", "clxyz101..."]
}

Exemplo

curl -X POST https://api.sendcloud.dev.br/v1/emails/batch \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@seudominio.com",
    "templateId": "tpl_abc123",
    "recipients": [
      { "to": "joao@exemplo.com", "templateData": { "name": "João" } },
      { "to": "maria@exemplo.com", "templateData": { "name": "Maria" } }
    ]
  }'

POST/v1/templates

Criar template

Cria um template Handlebars reutilizável com variáveis dinâmicas.

Campo	Tipo	Req.	Descrição
name	string	sim	Nome identificador do template
subject	string	sim	Assunto (suporta {{variavel}})
htmlContent	string	sim	Corpo HTML (suporta {{variavel}})
textContent	string	não	Versão texto plano (opcional)

Request body

json

{
  "name": "Boas-vindas",
  "subject": "Bem-vindo, {{name}}!",
  "htmlContent": "<h1>Olá, {{name}}!</h1><p>Obrigado por se cadastrar.</p>"
}

Response

json

{
  "id": "tpl_abc123...",
  "name": "Boas-vindas",
  "subject": "Bem-vindo, {{name}}!",
  "createdAt": "2026-01-01T12:00:00.000Z"
}

Exemplo

curl -X POST https://api.sendcloud.dev.br/v1/templates \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Boas-vindas",
    "subject": "Bem-vindo, {{name}}!",
    "htmlContent": "<h1>Olá, {{name}}!</h1>"
  }'

POST/v1/templates/:id/preview

Visualizar template renderizado

Renderiza o template com os dados fornecidos e retorna o HTML/texto final. Útil para testar variáveis antes de enviar.

Campo	Tipo	Req.	Descrição
data	object	não	Variáveis para substituição no template (ex: { "name": "João" })

Request body

json

{
  "data": {
    "name": "João",
    "confirmUrl": "https://exemplo.com/confirm/abc123"
  }
}

Response

json

{
  "subject": "Bem-vindo, João!",
  "html": "<h1>Olá, João!</h1>",
  "text": "Olá, João!"
}

Exemplo

curl -X POST "https://api.sendcloud.dev.br/v1/templates/TEMPLATE_ID/preview" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "name": "João" } }'

GET/v1/queue/stats

Estatísticas da fila

Retorna os contadores da fila de envio em tempo real — útil para monitorar picos de processamento.

Response

json

{
  "waiting": 12,
  "active": 3,
  "delayed": 5,
  "completed": 9820,
  "failed": 14,
  "paused": 0
}

Exemplo

curl "https://api.sendcloud.dev.br/v1/queue/stats" \
  -H "Authorization: Bearer SUA_API_KEY"

POST/v1/webhooks

Criar webhook

Registra um endpoint para receber notificações de eventos de email. O payload é assinado com HMAC-SHA256.

Campo	Tipo	Req.	Descrição
url	string	sim	URL que receberá os eventos via POST
events	string[]	sim	sent \| delivered \| bounced \| opened \| clicked \| failed \| unsubscribed

Request body

json

{
  "url": "https://suaapi.com/webhook",
  "events": ["delivered", "bounced", "opened", "unsubscribed"]
}

Response

json

{
  "id": "wh_abc123...",
  "url": "https://suaapi.com/webhook",
  "events": ["delivered", "bounced", "opened", "unsubscribed"],
  "active": true,
  "secret": "whsec_...",
  "createdAt": "2026-01-01T12:00:00.000Z"
}

Exemplo

curl -X POST https://api.sendcloud.dev.br/v1/webhooks \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://suaapi.com/webhook",
    "events": ["delivered", "bounced", "failed", "unsubscribed"]
  }'

GET/v1/suppressions

Listar supressões

Retorna endereços bloqueados por bounce permanente, unsubscribe ou adição manual. Emails para esses endereços são rejeitados com erro 422.

Campo	Tipo	Req.	Descrição
page	number	não	Página (padrão: 1)
limit	number	não	Itens por página, máx 100 (padrão: 50)

Response

json

{
  "data": [
    {
      "id": "sup_abc123...",
      "email": "usuario@exemplo.com",
      "reason": "bounce",
      "createdAt": "2026-01-01T12:00:00.000Z"
    }
  ],
  "total": 1
}

Exemplo

curl "https://api.sendcloud.dev.br/v1/suppressions?page=1&limit=50" \
  -H "Authorization: Bearer SUA_API_KEY"

POST/v1/suppressions

Adicionar à lista de supressão

Bloqueia manualmente um endereço de email. Idempotente — adicionar um email já bloqueado não gera erro.

Campo	Tipo	Req.	Descrição
email	string	sim	Endereço a bloquear

Request body

json

{
  "email": "usuario@exemplo.com"
}

Response

json

{
  "id": "sup_abc123...",
  "email": "usuario@exemplo.com",
  "reason": "manual",
  "createdAt": "2026-01-01T12:00:00.000Z"
}

Exemplo

curl -X POST https://api.sendcloud.dev.br/v1/suppressions \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "usuario@exemplo.com" }'

DELETE/v1/suppressions/:id

Remover da lista de supressão

Remove um endereço da lista de supressão, permitindo que futuros envios sejam processados normalmente.

Exemplo

curl -X DELETE "https://api.sendcloud.dev.br/v1/suppressions/sup_abc123" \
  -H "Authorization: Bearer SUA_API_KEY"

GET/v1/analytics

Analytics

Retorna totais e taxas de entrega, abertura, clique e bounce. Aceita filtro de data com from e to (ISO 8601).

Campo	Tipo	Req.	Descrição
from	string	não	Data de início em ISO 8601
to	string	não	Data de fim em ISO 8601

Response

json

{
  "total": 1250,
  "breakdown": {
    "delivered": 1100,
    "bounced": 50,
    "opened": 620,
    "clicked": 210
  },
  "rates": {
    "deliveryRate": 0.88,
    "bounceRate": 0.04,
    "openRate": 0.496,
    "clickRate": 0.168
  }
}

Exemplo

curl "https://api.sendcloud.dev.br/v1/analytics?from=2026-01-01T00:00:00Z&to=2026-01-31T23:59:59Z" \
  -H "Authorization: Bearer SUA_API_KEY"

GET/v1/analytics/daily

Volume diário

Retorna o volume de emails agrupado por dia nos últimos N dias. Dias sem envio retornam com total 0.

Campo	Tipo	Req.	Descrição
days	number	não	Janela em dias (1–90, padrão: 14)

Response

json

{
  "data": [
    {
      "date": "2026-01-20",
      "total": 145,
      "delivered": 138,
      "bounced": 4,
      "opened": 62
    }
  ]
}

Exemplo

curl "https://api.sendcloud.dev.br/v1/analytics/daily?days=14" \
  -H "Authorization: Bearer SUA_API_KEY"

Status de email

queued

Enfileirado para envio

scheduled

Agendado para envio futuro (scheduledFor)

sent

Aceito pelo servidor SMTP

delivered

Confirmado pelo servidor de destino

bounced

Rejeitado permanentemente (5xx) — endereço adicionado à supressão

failed

Erro interno ou timeout após todas as retentativas

opened

Pixel de rastreamento carregado pelo destinatário

clicked

Link rastreado clicado pelo destinatário

cancelled

Cancelado antes do envio via DELETE /v1/emails/:id

Eventos de webhook

sent

Email aceito pelo SMTP

delivered

Entrega confirmada

bounced

Bounce permanente (5xx)

failed

Falha após todas as retentativas

opened

Email aberto pelo destinatário

clicked

Link clicado pelo destinatário

unsubscribed

Destinatário cancelou inscrição via link no email

Unsubscribe automático

Todos os emails enviados via SendCloud recebem automaticamente um link de cancelamento de inscrição no rodapé e os headers List-Unsubscribe e List-Unsubscribe-Post (RFC 8058). Clientes como Gmail e Apple Mail exibem um botão de cancelamento de um clique sem que o usuário precise abrir o email.

Quando um destinatário cancela a inscrição, o endereço é adicionado à lista de supressão com reason: "unsubscribe". Futuros envios para esse endereço retornarão 422 recipient_suppressed. O evento unsubscribed é disparado para os webhooks configurados.

Para reativar um endereço, remova-o da supressão via DELETE /v1/suppressions/:id ou pelo painel.

SDK JavaScript
@sendcloud-dev-br/js

SDK oficial do SendCloud para Node.js, Deno, Edge e browser. Suporta CJS e ESM com tipagem completa.

Exemplo

// Instalação
npm install @sendcloud-dev-br/js

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

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

// Enviar email
const { id } = await sc.emails.send({
  from: 'noreply@seudominio.com',
  to: 'cliente@email.com',
  subject: 'Bem-vindo!',
  html: '<h1>Olá!</h1>',
})

// Envio com template
await sc.emails.send({
  from: 'noreply@seudominio.com',
  to: 'cliente@email.com',
  templateId: 'tpl_abc123',
  templateData: { nome: 'João', link: 'https://...' },
})

// Batch (até 500 destinatários)
await sc.emails.batch({
  from: 'noreply@seudominio.com',
  templateId: 'tpl_abc123',
  recipients: [
    { to: 'joao@email.com', templateData: { nome: 'João' } },
    { to: 'maria@email.com', templateData: { nome: 'Maria' } },
  ],
})

// Verificar assinatura de webhook (Edge/Node 18+)
const valid = await sc.webhooks.verify(
  rawBody,
  req.headers.get('x-sendcloud-signature') ?? '',
  process.env.WEBHOOK_SECRET!,
)

Documentação completa no npm. Código-fonte disponível no GitHub.

Prefere testar pela interface? Baixar Postman Collection — importe no Postman e configure as variáveis baseUrl e apiKey.

Pronto para começar?

Crie sua conta grátis, adicione seu domínio e envie os primeiros 500 emails — sem cartão de crédito.

Documentação da API

Quick Start

Autenticação

Enviar email

Listar emails

Detalhe do email

Linha do tempo do email

Exportar emails para CSV

Reenviar email

Cancelar email agendado

Envio em lote (batch)

Criar template

Visualizar template renderizado

Estatísticas da fila

Criar webhook

Listar supressões

Adicionar à lista de supressão

Remover da lista de supressão

Analytics

Volume diário

Status de email

Eventos de webhook

Unsubscribe automático

SDK JavaScript@sendcloud-dev-br/js

Pronto para começar?

SDK JavaScript
@sendcloud-dev-br/js