# Domínios — gestão via API

O mxout v0.4.0 gerencia domínios remetentes via API. Um domínio recém-adicionado nasce com status pending e só pode assinar e-mails depois que o DNS for validado pelo GET /check, que o promove a active.

Todos os endpoints abaixo exigem o header X-Auth-Token.

# Autenticação

X-Auth-Token: SEU_TOKEN

Token ausente ou incorreto retorna 401. Se MXOUT_AUTH_TOKEN não estiver definido no servidor, os endpoints ficam abertos — comportamento idêntico ao /send.

# POST /domains — adiciona um domínio

Gera um par de chaves DKIM RSA-2048, registra o domínio como pending e retorna os três registros DNS que precisam ser publicados antes do envio.

# Body da requisição

{
  "domain": "exemplo.com",
  "selector": "mxout"
}

# Exemplo de requisição

curl -X POST https://mxout.203.0.113.x/domains \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: SEU_TOKEN" \
  -d '{"domain": "exemplo.com", "selector": "mxout"}'

# Resposta de sucesso — 201

{
  "domain": "exemplo.com",
  "selector": "mxout",
  "dkim": {
    "host": "mxout._domainkey.exemplo.com",
    "type": "TXT",
    "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ..."
  },
  "spf": {
    "host": "exemplo.com",
    "type": "TXT",
    "value": "v=spf1 include:mxout.ccs.systems -all"
  },
  "dmarc": {
    "host": "_dmarc.exemplo.com",
    "type": "TXT",
    "value": "v=DMARC1; p=none; rua=mailto:dmarc@exemplo.com"
  },
  "note": "Publique os 3 registros DNS e execute GET /check/exemplo.com para ativar o domínio."
}

# Códigos de status

# Próxima etapa obrigatória

Após receber o 201, publique os três registros DNS retornados (DKIM, SPF e DMARC) no painel do seu provedor de DNS. Só então execute GET /check/exemplo.com para validar a configuração e ativar o domínio.

# GET /domains — lista os domínios

Retorna todos os domínios cadastrados com status e limites de envio.

# Exemplo de requisição

curl -s \
  -H "X-Auth-Token: SEU_TOKEN" \
  https://mxout.203.0.113.x/domains

# Resposta — 200

{
  "domains": [
    {
      "domain": "exemplo.com",
      "status": "active",
      "selector": "mxout",
      "limits": {
        "per_hour": 500,
        "per_day": 5000
      }
    },
    {
      "domain": "outro.com.br",
      "status": "pending",
      "selector": "mxout",
      "limits": {
        "per_hour": 0,
        "per_day": 0
      }
    }
  ]
}

# GET /domains/{dominio}/instructions — recupera instruções DNS

Retorna o mesmo JSON de instruções do POST /domains para um domínio já cadastrado. Use este endpoint para reconsultar os registros DNS sem precisar recriar o domínio ou regenerar a chave DKIM.

# Exemplo de requisição

curl -s \
  -H "X-Auth-Token: SEU_TOKEN" \
  https://mxout.203.0.113.x/domains/exemplo.com/instructions

# Resposta — 200

{
  "domain": "exemplo.com",
  "selector": "mxout",
  "dkim": {
    "host": "mxout._domainkey.exemplo.com",
    "type": "TXT",
    "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ..."
  },
  "spf": {
    "host": "exemplo.com",
    "type": "TXT",
    "value": "v=spf1 include:mxout.ccs.systems -all"
  },
  "dmarc": {
    "host": "_dmarc.exemplo.com",
    "type": "TXT",
    "value": "v=DMARC1; p=none; rua=mailto:dmarc@exemplo.com"
  },
  "note": "Publique os 3 registros DNS e execute GET /check/exemplo.com para ativar o domínio."
}

# Códigos de status

# Próximo passo

Com os registros DNS publicados, valide e ative o domínio com GET /check. O endpoint verifica DKIM, SPF e DMARC e promove o domínio de pending para active quando todos os registros estão corretos.