Newsletter

---
name: tray-newsletter
description: >
  API de Newsletter da Tray. Utilize quando o desenvolvedor precisar
  gerenciar assinaturas de newsletter da loja, incluindo listagem de assinantes,
  inscrição e confirmação de cadastro.
when_to_use: >
  Use quando o desenvolvedor mencionar: newsletter, assinatura de e-mail, opt-in,
  GET /newsletters, POST /newsletters, lista de e-mails, inscrever cliente na newsletter
  ou gerenciar assinantes.
when_not_to_use: >
  Não use para dados cadastrais do cliente (use tray-clientes). Use apenas para
  inscrição ou listagem de e-mails da newsletter da loja.
---

## MANDATORY: Tool Call(s) Required Before Answering

- **OBRIGATÓRIO:** `node skills/tray-dev/scripts/search_docs.mjs "<termo>"` — confirme o comportamento da API antes de gerar código.

## Antes de responder

> Execute estas verificações antes de gerar qualquer payload ou código:

1. Confirme o método HTTP e endpoint correto para a operação solicitada.
2. Identifique os campos obrigatórios listados neste documento — não omita nenhum.
3. Verifique que `access_token` não aparece como literal string no código gerado.
4. Confirme que esta é a skill correta para o recurso (leia `when_not_to_use` no frontmatter).

# API de Newsletter — Tray

Documentação oficial: https://developers.tray.com.br/#apis-de-newsletter

## Endpoints

| Método | Endpoint | Descrição |
|:--|:--|:--|
| GET | `/newsletters` | Listagem de assinantes da newsletter |
| POST | `/newsletters` | Cadastrar assinante |
| POST | `/newsletters/confirm` | Confirmar cadastro de newsletter |

**Autenticação:** `?access_token={token}`

## Exemplo de Inscrição

```json
{
  "Newsletter": {
    "email": "cliente@exemplo.com",
    "name": "João Silva"
  }
}
```

| Campo | Tipo | Obrigatório | Descrição |
|:--|:--|:--|:--|
| `email` | string | **Sim** | E-mail do assinante (único). Sem ele → HTTP 400. |
| `name` | string | Não | Nome do assinante |

> ⚠️ **`email` é obrigatório** na inscrição. A confirmação (double opt-in)
> aceita `email` **ou** `token` no corpo.

## Fluxo de Inscrição

1. `POST /newsletters` — cadastra o e-mail
2. `POST /newsletters/confirm` — confirma a inscrição (double opt-in)

## Paginação

`limit` (máximo 50, padrão 30), `page`.

## Boas Práticas

1. **LGPD** — obtenha consentimento explícito antes de inscrever
2. **Double opt-in** — use o endpoint de confirmação para validar o e-mail

## Como Usar no Claude Code

### Exemplos de Prompt

- "inscreve um cliente na newsletter com double opt-in"
- "lista todos os assinantes da newsletter da loja"
- "implementa o fluxo completo de inscrição com confirmação por e-mail"

### O que o Claude faz

1. Gera o código de inscrição com wrapper `Newsletter` (nome + e-mail)
2. Gera o código de confirmação via `POST /newsletters/confirm`
3. Explica o fluxo double opt-in e a obrigatoriedade de consentimento (LGPD)

### O que você recebe

- Código de inscrição com `{"Newsletter": {"email": "...", "name": "..."}}`
- Código de confirmação double opt-in
- Listagem de assinantes com paginação

### Pré-requisitos

- `access_token` configurado
- Consentimento explícito do usuário (LGPD)