# Domínios e DNS

> Como verificar um domínio no Couryo. Os registros DKIM (couryo1 e couryo2), return path e DMARC que a API gera, por que não há SPF no domínio principal e como o DMARC sobe até p=reject.

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

Para enviar com o seu domínio no `from`, ele precisa estar verificado. Isso prova aos provedores (Gmail, Microsoft, Yahoo, UOL...) que o Couryo pode enviar em seu nome, e é o que mais pesa para o e-mail chegar na caixa de entrada.

## Adicionar um domínio

Criar um domínio exige uma chave com escopo `admin` (ou o painel).

```bash title="cURL"
curl https://api.couryo.com/v1/domains \
  -H "Authorization: Bearer $COURYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "exemplo.com.br" }'
```

A resposta (`201`) traz os registros que você precisa criar, cada um com o próprio `status`:

```json title="Resposta 201"
{
  "id": "dom_7h2kq9w4x1abcdef",
  "name": "exemplo.com.br",
  "status": "pending",
  "dmarc_policy": "missing",
  "cloudflare_connected": false,
  "records": [
    { "purpose": "dkim", "type": "CNAME", "name": "couryo1._domainkey.exemplo.com.br", "value": "couryo1.7h2kq9w4x1abcdef.dkim.couryo.com", "status": "pending" },
    { "purpose": "dkim", "type": "CNAME", "name": "couryo2._domainkey.exemplo.com.br", "value": "couryo2.7h2kq9w4x1abcdef.dkim.couryo.com", "status": "pending" },
    { "purpose": "return_path", "type": "CNAME", "name": "bounces.exemplo.com.br", "value": "rp.couryo.com", "status": "pending" },
    { "purpose": "dmarc", "type": "TXT", "name": "_dmarc.exemplo.com.br", "value": "v=DMARC1; p=none; rua=mailto:dmarc@couryo.com; adkim=r; aspf=r", "status": "pending" }
  ],
  "created_at": "2026-10-07T18:30:00Z"
}
```

O alvo dos dois DKIM segue sempre o formato `<seletor>.<ID do domínio sem o prefixo dom_>.dkim.couryo.com`. O ID acima é um exemplo: copie os valores que aparecem no painel ou na resposta da API para o seu domínio.

> **Domínios por plano:** Grátis 1, Pro 10, Escala 50 e Empresa sem limite, somando todos os projetos da conta. Acima disso, a API responde `403` com o código [`domain_limit_reached`](https://couryo.com/docs/errors.md#domain_limit_reached); apagar um domínio libera a vaga. Cada domínio só pode estar cadastrado uma vez no Couryo (`409 domain_exists`).

## O que cada registro faz

| Registro | Tipo | Nome | Para que serve |
|---|---|---|---|
| **DKIM** | CNAME | `couryo1._domainkey` e `couryo2._domainkey` | Cada e-mail sai assinado com uma chave RSA de 2048 bits do seu domínio. Os dois seletores apontam para a zona do Couryo, onde ficam as chaves públicas: assinamos com um enquanto a chave do outro é trocada, então a rotação acontece sem você mexer no DNS. |
| **Return path** | CNAME | `bounces` | Endereço técnico do envelope, num subdomínio seu. É ele que leva o SPF (alinhado com o seu domínio) e faz as devoluções chegarem ao Couryo, que as transforma em eventos. |
| **DMARC** | TXT | `_dmarc` | Diz aos provedores o que fazer com e-mail que finge ser do seu domínio e para onde mandar relatórios. O `rua=mailto:dmarc@couryo.com` traz esses relatórios para o Couryo. Começa em `p=none`. |
| **Inbound** | MX | | Opcional, para receber e-mails no Couryo (em breve). |

### Por que não há SPF no domínio principal

O SPF é conferido no domínio do envelope (o return path), não no domínio do `From`. Como o envelope usa `bounces.exemplo.com.br`, que aponta para o Couryo por CNAME, o SPF passa e fica alinhado com o seu domínio. **Não mexa no SPF de `exemplo.com.br`**: o que você já tem (Google Workspace, Microsoft 365...) continua como está, e nenhuma das 10 consultas de DNS que o SPF permite é gasta com o Couryo.

> Se a resposta trouxer um registro `return_path` do tipo `MX` e um registro `spf` (`TXT v=spf1 include:spf.couryo.com ~all`), é o modo alternativo de return path. Crie os dois no subdomínio `bounces.`, nunca no domínio principal.

## Verificar

Com a Cloudflare conectada, o Couryo cria os registros e verifica sozinho. Em outros painéis, crie os registros e peça a verificação (escopo `admin`):

```bash title="cURL"
curl -X POST https://api.couryo.com/v1/domains/dom_7h2kq9w4x1abcdef/verify \
  -H "Authorization: Bearer $COURYO_API_KEY"
```

A verificação consulta o DNS público. Cada registro volta com `status`:

- `ok`: encontrado e correto.
- `pending`: ainda não encontrado. A propagação de DNS pode levar de minutos a algumas horas.
- `wrong`: encontrado com outro valor. O campo `found` mostra o que está publicado, para você comparar.

Se você já tem um DMARC próprio, ele é respeitado: o registro fica `ok` e o campo `found` mostra o seu valor. Dois registros DMARC no mesmo nome invalidam os dois e aparecem como `wrong`.

O domínio passa para `verified` quando DKIM, return path e DMARC estão `ok` e o motor do Couryo confirma a assinatura DKIM. Domínios pendentes são conferidos de novo sozinhos a cada 10 minutos por 72 horas; os verificados, uma vez por dia. O primeiro domínio verificado leva a conta do nível 0 para o nível 1 (veja [Limites e níveis](https://couryo.com/docs/limits.md)).

## Conectar a Cloudflare

No painel, em **Domínios**, use **Conectar Cloudflare** e cole um token da sua conta com a permissão **Zona > DNS > Editar** para o domínio. O Couryo cria os registros na sua zona e verifica na hora. Um DMARC que já existe nunca é sobrescrito.

Erros possíveis: `invalid_cloudflare_token` (token recusado ou sem a permissão) e `cloudflare_zone_not_found` (o token não alcança a zona do domínio).

## Dicas por painel

- **Cloudflare (à mão):** deixe os CNAMEs com o proxy desligado (nuvem cinza).
- **Registro.br:** no modo avançado de DNS, o campo de nome recebe só a parte antes do domínio (por exemplo, `couryo1._domainkey` e `bounces`).
- **Outros painéis:** alguns completam o domínio sozinhos. Se o registro aparecer como `couryo1._domainkey.exemplo.com.br.exemplo.com.br`, apague o domínio repetido do nome.

## DMARC de p=none até p=reject

O DMARC começa em `p=none`: os provedores só observam e mandam relatórios. Com os relatórios limpos por algumas semanas, vale subir para `p=quarantine` (e-mail falso vai para o spam) e depois para `p=reject` (e-mail falso é recusado). Conduzir essa subida com a sua permissão é o próximo passo do agente de entregabilidade (em breve).

O campo `dmarc_policy` do domínio mostra a política publicada hoje: `none`, `quarantine`, `reject` ou `missing`.

## Outros endpoints

| Método e caminho | Escopo | O que faz |
|---|---|---|
| `GET /v1/domains` | `read` | lista os domínios do projeto |
| `GET /v1/domains/{id}` | `read` | um domínio, com os registros |
| `DELETE /v1/domains/{id}` | `admin` | remove o domínio (`204`) e libera a vaga do plano |