# Postal

> Postal é uma plataforma de e-mail transacional e de marketing para o mercado brasileiro, com API REST (JSON), SMTP, webhooks assinados, domínios verificados, contatos, segmentos, tópicos, automações por eventos e dados no Brasil.

## O essencial

- URL base da API: `https://api.postal.so`.
- Autenticação: cabeçalho `Authorization: Bearer ps_...` (chave de API). Chaves de acesso total ou só de envio (`POST /emails`, `POST /emails/batch`, `POST /events`).
- Erros: `{"statusCode", "name", "message"}`; trate pelo `name` (código estável em inglês, como `validation_error`).
- Listas: paginação por cursor com `limit`, `after`, `before` e `has_more`.
- Idempotência: cabeçalho `Idempotency-Key` (1 a 256 caracteres, 24 horas) em `POST /emails`, `POST /emails/batch` e `POST /events`.
- Webhooks: padrão Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`), HMAC-SHA256 com o `signing_secret` (`whsec_...`).
- SDKs: Node.js (`npm install postal-so`) e PHP/Laravel (`composer require postal-so/postal-php`). CLI: `postal`, no pacote `postal-so`.

## Começando

- [Introdução](https://postal.so/docs): Documentação da API da Postal: envio de e-mails transacionais por API e SMTP, webhooks, domínios e referência completa.
- [Autenticação](https://postal.so/docs/autenticacao): Como autenticar na API da Postal com chaves de API de acesso total ou só de envio.
- [Primeiros passos](https://postal.so/docs/primeiros-passos): Envie o primeiro e-mail com a Postal em cURL, Node.js, Python, PHP ou Laravel.

## Conceitos

- [Erros](https://postal.so/docs/erros): Formato das respostas de erro da API da Postal, códigos e quando tentar de novo.
- [Paginação e filtros](https://postal.so/docs/paginacao): Paginação por cursor e filtros nas listas da API da Postal.
- [Limites](https://postal.so/docs/limites): Limites de requisições por segundo, cotas de envio e tamanhos máximos da API da Postal.
- [Idempotência](https://postal.so/docs/idempotencia): Use o cabeçalho Idempotency-Key para repetir envios sem duplicar e-mails.

## Guias

- [Webhooks](https://postal.so/docs/webhooks): Eventos, formato do payload, verificação de assinatura e novas tentativas dos webhooks da Postal.
- [SMTP](https://postal.so/docs/smtp): Configuração do SMTP da Postal: smtp.postal.so, portas 465 e 587, usuário postal e chave de API como senha.
- [Domínios e DNS](https://postal.so/docs/dominios-e-dns): Como configurar o DNS do seu domínio para enviar e receber e-mails com a Postal.
- [Marketing por e-mail](https://postal.so/docs/marketing-por-email): Boas práticas de e-mail marketing com a Postal: consentimento, LGPD, link de descadastro, List-Unsubscribe com um clique, página de preferências e tópicos.
- [Integre seu app](https://postal.so/docs/integre-seu-app): Como ligar o seu app à Postal: Stripe, Supabase, Clerk, Auth0 e Firebase viram contatos e eventos, e os e-mails de login saem pela Postal.
- [SDKs](https://postal.so/docs/sdks): SDKs oficiais da Postal para Node.js, PHP e Laravel: envio de e-mails, contatos, eventos, verificação de webhooks e o transporte de e-mail para o Laravel.
- [CLI](https://postal.so/docs/cli): CLI postal: login, whoami, envio de e-mails, eventos, contatos e domínios pelo terminal, com saída JSON.

## Referência da API

- [E-mails](https://postal.so/docs/api/emails): Referência dos endpoints de e-mails da API da Postal.
- [Recebidos e inboxes](https://postal.so/docs/api/recebidos): Referência dos endpoints de inboxes e e-mails recebidos.
- [Domínios](https://postal.so/docs/api/dominios): Referência dos endpoints de domínios da API da Postal.
- [Chaves de API](https://postal.so/docs/api/chaves-de-api): Referência dos endpoints de chaves de API da Postal.
- [Templates](https://postal.so/docs/api/templates): Referência dos endpoints de templates da API da Postal.
- [Webhooks](https://postal.so/docs/api/webhooks): Referência dos endpoints de webhooks da API da Postal.
- [Supressões](https://postal.so/docs/api/supressoes): Referência dos endpoints da lista de supressão da Postal.
- [Logs](https://postal.so/docs/api/logs): Referência dos endpoints de logs da API da Postal.
- [Exportações](https://postal.so/docs/api/exportacoes): Referência dos endpoints de exportação da Postal.
- [Uso e métricas](https://postal.so/docs/api/uso): Referência dos endpoints de uso e métricas da Postal.
- [IA](https://postal.so/docs/api/ia): Referência dos endpoints de IA da Postal.
- [Planos](https://postal.so/docs/api/planos): Referência do endpoint público de planos da Postal.

## Audiência

- [Contatos](https://postal.so/docs/api/contatos): Referência dos endpoints de contatos da API da Postal.
- [Propriedades de contato](https://postal.so/docs/api/propriedades-de-contato): Referência dos endpoints de propriedades de contato da Postal.
- [Importação de contatos](https://postal.so/docs/api/importacao-de-contatos): Como importar contatos de um CSV pela API da Postal.
- [Segmentos](https://postal.so/docs/api/segmentos): Referência dos endpoints de segmentos da Postal.
- [Tópicos](https://postal.so/docs/api/topicos): Referência dos endpoints de tópicos da Postal.
- [Formulários](https://postal.so/docs/api/formularios): Referência dos endpoints de formulários e do envio público da Postal.

## Marketing

- [Campanhas](https://postal.so/docs/api/broadcasts): Referência dos endpoints de campanhas de e-mail (/broadcasts) da API da Postal.
- [Automações](https://postal.so/docs/api/automacoes): Referência dos endpoints de automações e execuções da API da Postal.
- [Eventos](https://postal.so/docs/api/eventos): Referência dos endpoints de eventos personalizados da API da Postal.

## Integrações

- [Stripe](https://postal.so/docs/integracoes/stripe): Integração da Postal com o Stripe: webhooks de clientes, assinaturas e faturas viram contatos e eventos.
- [Supabase](https://postal.so/docs/integracoes/supabase): Integração da Postal com o Supabase: Database Webhooks em auth.users e o Send Email Hook para os e-mails de login.
- [Clerk](https://postal.so/docs/integracoes/clerk): Integração da Postal com o Clerk: webhooks de usuários e lista de espera viram contatos e eventos.
- [Auth0](https://postal.so/docs/integracoes/auth0): Integração da Postal com o Auth0: Log Stream de cadastros e logins, e o provedor de e-mail customizado.
- [Firebase Auth](https://postal.so/docs/integracoes/firebase): Integração da Postal com o Firebase Authentication por Cloud Functions.
- [Better Auth](https://postal.so/docs/integracoes/better-auth): Como enviar os e-mails do Better Auth pela API da Postal.
- [Auth.js (NextAuth)](https://postal.so/docs/integracoes/authjs): Como enviar os e-mails de login do Auth.js (NextAuth) pela API da Postal.

## Para agentes de IA

- [Skill do Postal](https://raw.githubusercontent.com/ministralhq/postal-node/main/skills/postal/SKILL.md): ensina Claude Code, Codex e Cursor a integrar o Postal num app (instalar o SDK, chave de API, e-mails, eventos, contatos e webhooks).
- [SDK Node.js](https://github.com/ministralhq/postal-node): pacote `postal-so`, com a CLI `postal`.
- [SDK PHP e Laravel](https://github.com/ministralhq/postal-php): pacote `postal-so/postal-php`, com o transporte de e-mail `postal` para o Laravel.