# CoffeeMail — Plataforma de Email Transacional para o Brasil

> CoffeeMail é uma plataforma brasileira de email transacional auto-hospedada, operada em São Paulo com Postfix próprio. Faturamento em BRL via PIX, NF-e automática, LGPD compliant (DSAR, exportação e exclusão via API, audit log imutável), IP warmup inteligente, webhooks assinados com HMAC SHA-256, e SDK Node oficial @coffeemail/node com retorno seguro { data, error }.

> **Stack público da plataforma**: API REST em `/v1/product/*` (consumida via API Key `cm_live_*`), SDK Node `@coffeemail/node`, dashboard em `/app/*` (interno, cookie HttpOnly).

## Documentação pública

- [Visão geral](https://coffeemail.com.br/docs): Apresentação da plataforma, base URL e contratos públicos.
- [Início rápido](https://coffeemail.com.br/docs/quickstart): Envie seu primeiro email em 5 minutos com o SDK Node ou cURL.
- [Referência da API](https://coffeemail.com.br/docs/api): Todos os endpoints REST públicos da Product API.
- [Códigos de erro](https://coffeemail.com.br/docs/api/errors): Tabela de status HTTP e mapeamento para classes do SDK.
- [Guias](https://coffeemail.com.br/docs/guides): Tutoriais passo-a-passo.

### Guias específicos

- [Envie seu primeiro email](https://coffeemail.com.br/docs/guides/send-first-email): Da criação de conta à entrega confirmada.
- [Verifique seu domínio](https://coffeemail.com.br/docs/guides/verify-domain): SPF, DKIM, DMARC com validação automática.
- [Templates com React Email](https://coffeemail.com.br/docs/guides/react-email-templates): `@react-email/components` + `renderPreview`.
- [Webhooks assinados](https://coffeemail.com.br/docs/guides/webhooks): HMAC SHA-256, idempotência e retries.
- [Audiências e Broadcasts](https://coffeemail.com.br/docs/guides/audiences-broadcasts): Importação de contatos e disparo com headers RFC 8058.
- [Segurança e Compliance](https://coffeemail.com.br/docs/security): LGPD, ISO 27001, SOC 2, criptografia e retenção.
- [Changelog](https://coffeemail.com.br/docs/changelog): Histórico de releases da plataforma.
- [Suporte](https://coffeemail.com.br/docs/support): Canais oficiais (status, email, comunidade GitHub).

## SDK Node oficial

- Pacote: [`@coffeemail/node`](https://www.npmjs.com/package/@coffeemail/node) (ESM + CJS, TypeScript estrito, locale pt-BR/en/es).
- Recursos: `emails`, `domains`, `templates`, `audiences` (+ `audiences.contacts`), `broadcasts`, `suppressions`, `webhooks` (com `verifySignature` HMAC), `stats`.
- Retorno seguro: `{ data, error }` — erros tipados (`ValidationError`, `AuthenticationError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `RateLimitError`, `PaymentRequiredError`, `InternalServerError`, `NetworkError`).
- Documentação inline via TSDoc com exemplos em cada método.

## Endpoints públicos (Product API)

Base URL: `https://api.coffeemail.com.br/v1/product`. Autenticação: `Authorization: Bearer cm_live_<key>`. Headers auxiliares: `Content-Type: application/json`, `Accept-Language: pt-BR|en|es`.

- Emails: `POST /emails`, `POST /emails/batch`, `GET /emails`, `GET /emails/:id`, `GET /emails/:id/events`, `POST /emails/:id/cancel`, `POST /emails/:id/resend`.
- Domínios: `POST /domains`, `GET /domains`, `GET /domains/:id`, `DELETE /domains/:id`, `POST /domains/:id/verify`, `POST /domains/:id/health`.
- Templates: `POST /templates`, `GET /templates`, `GET /templates/:id`, `PATCH /templates/:id`, `DELETE /templates/:id`, `POST /templates/preview`.
- Audiências: `POST /audiences`, `GET /audiences`, `GET /audiences/:id`, `DELETE /audiences/:id`. Contatos: `POST /audiences/:id/contacts`, `GET /audiences/:id/contacts`, `DELETE /audiences/:id/contacts/:contactId`.
- Broadcasts: `POST /broadcasts`, `GET /broadcasts`, `GET /broadcasts/:id`, `POST /broadcasts/:id/send`, `POST /broadcasts/:id/cancel`.
- Supressões: `GET /suppressions`, `POST /suppressions`, `GET /suppressions/:id`, `DELETE /suppressions/:id`, `POST /suppressions/:id/reactivate`.
- Webhooks: `POST /webhooks`, `GET /webhooks`, `GET /webhooks/:id`, `PUT /webhooks/:id`, `DELETE /webhooks/:id`, `POST /webhooks/:id/test`.
- Estatísticas: `GET /stats`.

> Endpoints `/v1/platform/*` (dashboard via cookie de sessão) e `/v1/internal/*` (infra Postfix/fila) **não** fazem parte deste contrato público.

## Eventos de Webhook

`email.sent`, `email.delivered`, `email.bounced`, `email.complained`, `email.opened`, `email.clicked`, `email.failed`, `email.suppressed`, `email.delivery_delayed`. Assinatura via header `X-CoffeeMail-Signature` (HMAC SHA-256). Validação local: `coffeemail.webhooks.verifySignature({ payload, signature, secret })`.

## Conformidade

- LGPD nativo: DSAR em 15 dias via `GET /v1/platform/me/data-export`, exclusão via `DELETE /v1/platform/me`, audit log imutável.
- ISO 27001 e SOC 2 Type II.
- Criptografia AES-256 em repouso, TLS 1.3 em trânsito.
- Servidores em São Paulo, Brasil. Marco Civil da Internet compliant.

## Billing

- Gateway brasileiro (AbacatePay) em BRL — PIX recorrente e cartão.
- NF-e emitida automaticamente no CNPJ do cliente após cada cobrança.
- Planos: Free (1.000 emails/mês, 1 domínio, 2 API keys), Pro (50.000 emails/mês, MFA obrigatório, IP dedicado opcional), Enterprise (volume customizado, SLA dedicado).

## Contato

- Suporte: support@coffeemail.com.br
- DPO (LGPD): dpo@coffeemail.com.br
- Vendas: sales@coffeemail.com.br

## Idiomas suportados

- Português do Brasil (pt-BR) — padrão
- English (en)
- Español (es)