Canal e-mail

Enviando um e-mail

curl -X POST https://planoit.aviait.com.br/api/v1/messages \
  -H "Authorization: Bearer pln_prd_<key_id>_<secret>" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "templateSlug": "boas-vindas",
    "recipient": "destinatario@exemplo.com",
    "payload": { "nome": "Maria" }
  }'

Resposta (202 Accepted):

{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "queued" }

Campos do corpo

Campo	Obrigatório	Descrição
`templateSlug`	sim	Slug do template cadastrado (`channel='email'`). Resolve primeiro um template da sua aplicação; se não existir, cai no template global da plataforma com o mesmo slug.
`recipient`	sim	E-mail do destinatário.
`channel`	não	Omita ou envie `"email"` — é o default.
`category`	não	`transactional` (default), `notification` ou `marketing`.
`senderId`	não	UUID do remetente verificado (`application_senders`). Se omitido, usa o remetente default da sua aplicação.
`subjectOverride`	não	Sobrescreve o assunto do template só para este envio.
`payload`	não	Objeto com as variáveis do template (Handlebars).
`correlationId`	não	Identificador seu, livre, devolvido na telemetria interna.

status na resposta é "queued" (enfileirado normalmente) ou "suppressed" (o destinatário já pediu descadastro desta aplicação — veja abaixo).

Remetente verificado

Todo envio de e-mail precisa de um application_senders verificado (verified_at preenchido) para a sua aplicação. Isso é configurado por um administrador — se a chamada responder 403 SENDER_NOT_VERIFIED, peça para verificar o remetente antes de insistir.

Supressão self-service (descadastro)

Todo e-mail enviado pelo Planoit carrega automaticamente os headers RFC 8058:

List-Unsubscribe: <https://planoit.aviait.com.br/api/v1/unsubscribe?token=...>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Isso permite que o próprio cliente de e-mail do destinatário (Gmail, Outlook) ofereça um botão “Cancelar inscrição” nativo. A supressão é por aplicação — um destinatário que se descadastra da sua aplicação continua recebendo e-mails de outras aplicações que usam o Planoit. Depois de suprimido, novos envios para o mesmo destinatário/aplicação nascem com status: "suppressed" em vez de "queued" — não é um erro, é um sinal de que a mensagem não foi para a fila de disparo real.

Você não precisa implementar nada para ganhar esse comportamento — ele é automático em todo e-mail enviado pelo Planoit.

Erros específicos deste canal

`code`	HTTP	Quando acontece
`SENDER_NOT_VERIFIED`	403	O remetente (explícito via `senderId` ou o default da aplicação) ainda não foi verificado.
`TEMPLATE_NOT_FOUND`	404	Nenhum template com esse `templateSlug` para o canal `email` (nem da aplicação, nem global).

Veja a referência completa de erros para os códigos comuns a todos os canais (autenticação, validação, idempotência).