E-mails

Com estes endpoints, um sistema externo envia um e-mail para um destinatário pelo SquadOS e acompanha a entrega. Use para e-mails disparados por eventos do seu sistema, como confirmação de cadastro, boleto gerado ou lembrete de reunião. Para enviar a uma lista inteira, use as campanhas do painel.

O envio segue o mesmo caminho dos e-mails das automações: o SquadOS respeita descadastros e devoluções, cobra os créditos de e-mail e registra a entrega.

Todos os endpoints exigem o header Authorization: Bearer pk_.... No envio, inclua também Content-Type: application/json.

Base URL: https://api.squados.io/v1

Consulte Autenticação para obter sua chave, e Erros para a referência de códigos.

Qual token usar

Acesso total envia por qualquer remetente da organização.
Apenas enviar e-mails envia só pelos remetentes marcados em Remetentes permitidos quando o token foi gerado, e só alcança estes dois endpoints. Prefira este escopo para uma integração que só envia e-mail.

`POST /emails`

Coloca na fila um e-mail para um destinatário. O envio é assíncrono: a resposta confirma que o e-mail entrou na fila, e o status final é lido em GET /emails/{id}.

Corpo

Campo	Tipo	Obrigatório	Descrição
`from`	string	Sim	Endereço de um remetente da organização, como `contato@suaempresa.com.br`. Maiúsculas e minúsculas não importam.
`to`	string	Sim	Um único endereço de destino.
`subject`	string	Sim	Assunto, com até 300 caracteres.
`html`	string	Um dos dois	Corpo em HTML, enviado como você escreveu. Até 200.000 caracteres.
`text`	string	Um dos dois	Corpo em texto simples. Até 200.000 caracteres.

Envie html, text ou os dois:

só text: o SquadOS monta o HTML a partir dos parágrafos do texto;
só html: o HTML vai como você escreveu, com as variáveis preenchidas e o rodapé acrescentado;
os dois: o HTML é o corpo principal e o texto vira a versão em texto simples do mesmo e-mail.

Prefira HTML com menos de 100 KB: provedores como o Gmail cortam mensagens maiores.

curl -X POST "https://api.squados.io/v1/emails" \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "contato@suaempresa.com.br",
    "to": "cliente@exemplo.com",
    "subject": "Seu cadastro foi confirmado",
    "html": "<p>Olá, {{contact.first_name | \"tudo bem\"}}! Seu cadastro está ativo.</p>",
    "text": "Olá! Seu cadastro está ativo."
  }'

Resposta — 202 Accepted

{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "queued",
  "from": "contato@suaempresa.com.br",
  "to": "cliente@exemplo.com"
}

Guarde o id para consultar a entrega.

O que acontece com o destinatário

O destinatário vira um contato da organização: o SquadOS cria o contato quando o endereço ainda não existe. É por ele que descadastro, devoluções e o histórico de envios funcionam.
Quem descadastrou ou teve devolução definitiva não recebe: a API recusa o envio antes de colocá-lo na fila.
O e-mail sai com o rodapé do SquadOS: nome e endereço da organização e um link para a pessoa gerenciar o recebimento.

Personalização

O assunto e o corpo aceitam três variáveis do contato:

Variável	Vira
`{{contact.first_name}}`	Primeiro nome do contato
`{{contact.name}}`	Nome completo do contato
`{{contact.email}}`	Endereço do contato

Para quando o contato não tem nome, informe um texto reserva depois de |: {{contact.first_name | "tudo bem"}}. Qualquer outra variável entre {{ }} faz o envio ser recusado com 400 e reason: "unknown_merge_tags", com as variáveis desconhecidas em tags.

Erros do envio

A API recusa na ordem do que você consegue corrigir: corpo, remetente, permissão do token, domínio, envio da organização, destinatário e créditos.

Status	`code`	`reason`	Quando
400	`invalid_request`	—	Corpo inválido: `from` ou `to` não é um endereço válido, `to` tem mais de um endereço, falta `subject`, faltam `html` e `text`, ou um campo passou do limite. O campo vem em `field`.
400	`invalid_request`	`unknown_merge_tags`	Variável desconhecida no assunto ou no corpo. A lista vem em `tags`.
403	`forbidden`	`sender_not_allowed`	Token Apenas enviar e-mails usando um remetente que não está entre os permitidos.
403	`forbidden`	`email_module_blocked`	A organização não pode enviar e-mail agora. O motivo vem em `blocked_reason`: `plan` (o plano não inclui e-mail), `not_activated`, `paused`, `disabled` ou `setup_failed`.
403	`forbidden`	`insufficient_credits`	A organização não tem créditos de e-mail suficientes.
404	`not_found`	`sender_not_found`	`from` não é um remetente da organização.
409	`conflict`	`sender_domain_not_verified`	O domínio do remetente ainda não foi verificado.
409	`conflict`	`recipient_suppressed`	O destinatário descadastrou ou teve devolução e não pode receber. O motivo vem em `suppression_reason`: `hard_bounce`, `complaint`, `soft_bounce_streak`, `unsubscribe` ou `manual`.
409	`conflict`	`contact_conflict`	O endereço pertence a um contato com conflito de identidade na organização.

{
  "error": "The sender domain is not verified yet",
  "code": "conflict",
  "reason": "sender_domain_not_verified",
  "field": "from"
}

`GET /emails/{id}`

Lê o status de um e-mail enviado pela API.

curl "https://api.squados.io/v1/emails/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta — 200 OK

{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "delivered",
  "to": "cliente@exemplo.com",
  "subject": "Seu cadastro foi confirmado",
  "error_code": null,
  "created_at": "2026-10-25T12:00:00Z",
  "sent_at": "2026-10-25T12:00:04Z",
  "updated_at": "2026-10-25T12:00:09Z"
}

Campo	Tipo	Descrição
`id`	uuid	O `id` devolvido pelo envio.
`status`	string	Situação da entrega. Veja a tabela abaixo.
`to`	string ou `null`	Destinatário.
`subject`	string	Assunto enviado.
`error_code`	string ou `null`	Código da falha informado pelo provedor, quando houver.
`created_at`	date-time	Quando o envio foi recebido.
`sent_at`	date-time ou `null`	Quando o e-mail saiu.
`updated_at`	date-time	Última mudança de status.

`status`	Significado
`queued`	Na fila, ainda não saiu.
`sent`	Saiu e foi aceito pelo provedor de envio.
`delivered`	O servidor do destinatário confirmou a entrega.
`bounced`	Devolvido pelo servidor do destinatário.
`complained`	O destinatário marcou como spam.
`failed`	Não foi possível enviar. Veja `error_code`.
`suppressed`	Não enviado porque o destinatário não pode mais receber.

Consulte com intervalos, não em laço contínuo: a entrega costuma levar de segundos a alguns minutos.

Um id inválido, de outra organização ou de um e-mail que não saiu pela API responde 404 not_found. Um token Apenas enviar e-mails só enxerga os e-mails enviados pelos remetentes permitidos para ele; os demais também respondem 404.