Adicionar e verificar um domínio

Para enviar de hello@acme.com, você prova que é dono de acme.com publicando registros DNS. A verificação configura a assinatura DKIM (para que os destinatários saibam que o e-mail é realmente seu) e um return path personalizado (para que o SPF e o DMARC fiquem alinhados com o seu domínio).

Antes de adicionar um domínio

As equipes novas preenchem primeiro um breve perfil de envio, e alguns domínios são recusados (provedores de e-mail gratuitos e domínios registrados nos últimos 7 dias). Veja Verificação da conta e limites de envio.

1. Adicione o domínio

   Node.js

   add-domain.ts

   import { SpacePost } from "@spacepost/node";
   
   const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);
   
   const { data: domain, error } = await spacepost.domains.create({ name: "acme.com" });
   if (error) throw new Error(`${error.name}: ${error.message}`);
   
   console.log(domain.id, domain.status); // "not_started" or "pending"
   for (const r of domain.records ?? []) {
     console.log(`${r.type.padEnd(5)} ${r.name} -> ${r.value}${r.priority ? ` (priority ${r.priority})` : ""}`);
   }

   cURL

   curl -X POST https://api.spacepost.dev/domains \
     -H "Authorization: Bearer $SPACEPOST_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "name": "acme.com" }'

   Python

   r = requests.post(
       "https://api.spacepost.dev/domains",
       headers={"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"},
       json={"name": "acme.com"},
   )
   for rec in r.json()["records"]:
       print(rec["type"], rec["name"], rec["value"])

   Você também pode usar o painel ou spacepost domains add acme.com.

2. Crie os registros DNS

   A resposta contém um array records e um array recommended_records (DMARC):

   Response (abridged)

   {
     "object": "domain",
     "id": "0192e1c4-0000-7000-8000-000000000001",
     "name": "acme.com",
     "status": "not_started",
     "region": "eu-central-1",
     "open_tracking": false,
     "click_tracking": false,
     "records": [
       { "record": "DKIM", "name": "a1b2c3d4e5f6._domainkey", "type": "CNAME", "ttl": "Auto", "status": "not_started", "value": "a1b2c3d4e5f6.dkim.amazonses.com" },
       { "record": "DKIM", "name": "g7h8i9j0k1l2._domainkey", "type": "CNAME", "ttl": "Auto", "status": "not_started", "value": "g7h8i9j0k1l2.dkim.amazonses.com" },
       { "record": "DKIM", "name": "m3n4o5p6q7r8._domainkey", "type": "CNAME", "ttl": "Auto", "status": "not_started", "value": "m3n4o5p6q7r8.dkim.amazonses.com" },
       { "record": "SPF", "name": "send", "type": "MX", "ttl": "Auto", "status": "not_started", "value": "feedback-smtp.eu-central-1.amazonses.com", "priority": 10 },
       { "record": "SPF", "name": "send", "type": "TXT", "ttl": "Auto", "status": "not_started", "value": "\"v=spf1 include:amazonses.com ~all\"" }
     ],
     "recommended_records": [
       { "record": "DMARC", "name": "_dmarc", "type": "TXT", "ttl": "Auto", "status": "not_started", "value": "\"v=DMARC1; p=none;\"" }
     ]
   }

   Adicione-os no seu provedor de DNS. Veja os registros explicados abaixo e os guias por provedor.

3. Verifique

   As alterações de DNS podem levar alguns minutos (raramente, horas). O SpacePost reverifica os domínios pendentes automaticamente, e você pode disparar uma verificação a qualquer momento:

   Node.js

   verify-domain.ts

   import { SpacePost } from "@spacepost/node";
   
   const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);
   const id = "0192e1c4-0000-7000-8000-000000000001";
   
   const { error } = await spacepost.domains.verify(id); // asks SpacePost to re-check DNS now
   if (error) throw new Error(error.message);
   
   const { data: domain } = await spacepost.domains.get(id);
   console.log(domain?.status); // "verified" once DKIM is confirmed

   cURL

   curl -X POST https://api.spacepost.dev/domains/$DOMAIN_ID/verify -H "Authorization: Bearer $SPACEPOST_API_KEY"
   curl https://api.spacepost.dev/domains/$DOMAIN_ID -H "Authorization: Bearer $SPACEPOST_API_KEY"

   CLI

   spacepost domains verify acme.com
   spacepost domains doctor acme.com   # looks up each record live and tells you what is missing or wrong

Os registros explicados

Os nomes de registros na API são relativos ao seu domínio (send, _dmarc, a1b2c3d4e5f6._domainkey). Alguns provedores de DNS querem o nome completo (send.acme.com); os guias por provedor informam qual é o caso.

Registro	Tipo	Nome	Valor	Finalidade
DKIM (x3)	CNAME	<token>._domainkey	<token>.dkim.amazonses.com	Publica as chaves públicas que o Amazon SES rotaciona para você (“Easy DKIM”). Os destinatários as usam para verificar que cada mensagem foi assinada pelo seu domínio e não foi alterada. Obrigatório: a verificação depende dos três.
Return path	MX	send	feedback-smtp.<region>.amazonses.com, prioridade 10	Recebe as notificações de rejeição e de reclamação endereçadas a send.acme.com. Junto com o TXT abaixo, forma um domínio MAIL FROM personalizado.
Return path	TXT	send	v=spf1 include:amazonses.com ~all	SPF do subdomínio do return path. Como o remetente do envelope está no seu domínio, o SPF fica alinhado com o seu endereço From, o que o DMARC exige.
DMARC (recomendado)	TXT	_dmarc	v=DMARC1; p=none;	Diz aos destinatários o que fazer com e-mails que falham na autenticação e é exigido pelo Gmail e pelo Yahoo de remetentes em massa. Veja DMARC.

Aspas em TXT

A API mostra os valores TXT entre aspas ("v=spf1 ..."). A maioria dos painéis de DNS adiciona as aspas por conta própria; informe o valor sem elas.

Nota

O subdomínio send pode ser renomeado com custom_return_path ao adicionar o domínio. Veja Return-Path personalizado.

Está criando uma plataforma que envia e-mails para os seus próprios clientes? Passe tenant_id (um id de tenant ou o seu external_id) para tornar o domínio pertencente a um tenant; os e-mails enviados dele passam a ser atribuídos a esse tenant automaticamente. Veja Modo plataforma.

Status

Status	Significado
not_started	Domínio adicionado, DNS ainda não detectado.
pending	O SpacePost está verificando o DNS.
verified	O DKIM está confirmado. Você pode enviar deste domínio.
temporary_failure	Uma consulta falhou temporariamente. Ela é repetida automaticamente.
failed	O DNS não foi encontrado em 72 horas, ou um registro está errado. Corrija os registros e chame a verificação novamente.

O domínio passa a verified assim que o DKIM é aprovado. Se faltarem apenas os registros do return path, os e-mails ainda são enviados, mas o alinhamento do SPF volta a usar o domínio da Amazon, o que enfraquece o alinhamento do DMARC. Corrija isso para obter a melhor entregabilidade.

Cada registro em records tem o seu próprio status, com os mesmos valores, para você ver exatamente qual está faltando.

Enviar de subdomínios

Se acme.com estiver verificado, você pode enviar de qualquer subdomínio (news@mail.acme.com). Verificar o próprio subdomínio (mail.acme.com) é a melhor prática para e-mails de marketing, porque mantém a reputação separada da do seu domínio transacional.

Limites

Plano	Domínios
Free	3
Pro	10
Scale	1.000

Adicionar um domínio que outra equipe já registrou retorna 422 validation_error (“Domain already registered”).

Guias por provedor de DNS

Cloudflare

AWS Route 53

Vercel

Namecheap

GoDaddy

Google Domains / Squarespace

DigitalOcean

Hetzner

Travou? Veja Solução de problemas.