# Templates salvos

> Templates do Couryo em HTML ou MJML com variáveis {{nome}}, versões e pré-visualização, e como enviar com template + variables.

Fonte: https://couryo.com/docs/templates

Salve o HTML do e-mail uma vez e mande só os dados em cada envio. Os templates ficam no projeto, aceitam HTML ou [MJML](https://mjml.io) e têm variáveis entre chaves duplas.

## Variáveis

- Escreva `{{nome}}` no assunto, no HTML ou no texto. Para valores aninhados, use ponto: `{{pedido.numero}}`.
- Nomes aceitos: letras, números e `_`, começando por letra ou `_`. Um nome inválido, como `{{nome completo}}`, é recusado ao salvar.
- No HTML, os valores são **escapados** (`<` vira `&lt;`), então dados do usuário não quebram o layout nem injetam código.
- Valores podem ser texto, número ou verdadeiro/falso. **Toda variável usada precisa de valor**: se faltar alguma, o envio é recusado com `invalid_field` e `param` = `variables.<nome>`.
- Sem parte em texto, o Couryo gera uma a partir do HTML (os links ficam com o endereço entre parênteses).

## Criar

```bash title="cURL"
curl https://api.couryo.com/v1/templates \
  -H "Authorization: Bearer $COURYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "boas-vindas",
    "format": "html",
    "subject": "Bem-vinda, {{nome}}!",
    "html": "<h1>Olá, {{nome}}</h1><p>Seu pedido {{pedido.numero}} foi confirmado.</p>"
  }'
```

A resposta traz o `id` (`tpl_...`), a `version` (começa em 1) e a lista de `variables` encontradas. O `name` é único no projeto e pode ser usado no lugar do `id`. Criar, mudar e apagar exigem uma chave `admin`; ler e pré-visualizar, `read`.

Com `"format": "mjml"`, o MJML é compilado ao salvar; se tiver erro, a resposta é `invalid_field` com `param` = `html` e a mensagem do MJML.

## Enviar com um template

```bash title="cURL"
curl https://api.couryo.com/v1/emails \
  -H "Authorization: Bearer $COURYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Loja <oi@exemplo.com.br>",
    "to": "ana@exemplo.com.br",
    "template": "boas-vindas",
    "variables": { "nome": "Ana", "pedido": { "numero": 1042 } }
  }'
```

- Com `template`, o `subject` é opcional (vale o do template); se você mandar um, ele vence.
- `template` e `html`/`text` no mesmo pedido: `invalid_field` com `param` = `template`.
- O envio usa a versão atual do template, e o e-mail guarda qual foi: `GET /v1/emails/{id}` traz `"template": { "id": "tpl_...", "version": 2 }`.
- Também vale no [lote](https://couryo.com/docs/sending.md#envio-em-lote) e na checagem `POST /v1/emails/check`, que confere o conteúdo já com as variáveis.

## Versões

Mudar `subject`, `html` ou `text` (`PATCH /v1/templates/{id}`) cria uma versão nova; trocar só o `name` não. E-mails já enviados não mudam. `GET /v1/templates/{id}/versions` lista todas, da mais nova para a mais antiga.

## Pré-visualizar

```bash title="cURL"
curl https://api.couryo.com/v1/templates/boas-vindas/preview \
  -H "Authorization: Bearer $COURYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "variables": { "nome": "Ana" }, "version": 1 }'
```

Devolve `subject`, `html` (MJML já compilado), `text` e `missing_variables`, a lista do que faltaria para enviar. Nada é enviado. No painel, a tela **Templates** faz o mesmo, com o e-mail renderizado ao lado.

## Endpoints

| Método e caminho | Escopo | O que faz |
|---|---|---|
| `GET /v1/templates` | `read` | lista os templates do projeto |
| `POST /v1/templates` | `admin` | cria (**201**) |
| `GET /v1/templates/{id}` | `read` | um template (por `id` ou `name`), versão atual |
| `PATCH /v1/templates/{id}` | `admin` | muda `name`, `subject`, `html` ou `text` |
| `DELETE /v1/templates/{id}` | `admin` | apaga (**204**) |
| `GET /v1/templates/{id}/versions` | `read` | versões |
| `POST /v1/templates/{id}/preview` | `read` | pré-visualização com variáveis |