Aggiungere e verificare un dominio

Per inviare da hello@acme.com dimostri di possedere acme.com pubblicando dei record DNS. La verifica configura la firma DKIM (così i destinatari sanno che l’email è davvero tua) e un return path personalizzato (così SPF e DMARC risultano allineati con il tuo dominio).

Prima di aggiungere un dominio

I nuovi team completano prima un breve profilo di invio e alcuni domini vengono rifiutati (provider di posta gratuiti, domini registrati negli ultimi 7 giorni). Vedi Verifica dell’account e limiti di invio.

1. Aggiungi il dominio

   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"])

   Puoi usare anche la dashboard oppure spacepost domains add acme.com.

2. Crea i record DNS

   La risposta contiene un array records e un 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;\"" }
     ]
   }

   Aggiungili presso il tuo provider DNS. Vedi i record spiegati qui sotto e le guide per provider.

3. Verifica

   Le modifiche DNS possono richiedere qualche minuto (raramente ore). SpacePost ricontrolla automaticamente i domini in attesa e puoi avviare un controllo in qualsiasi 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

I record spiegati

I nomi dei record nell’API sono relativi al tuo dominio (send, _dmarc, a1b2c3d4e5f6._domainkey). Alcuni provider DNS vogliono il nome completo (send.acme.com); le guide per provider indicano quali.

Record	Tipo	Nome	Valore	Scopo
DKIM (x3)	CNAME	<token>._domainkey	<token>.dkim.amazonses.com	Pubblica le chiavi pubbliche che Amazon SES ruota per te (“Easy DKIM”). I destinatari le usano per verificare che ogni messaggio sia stato firmato dal tuo dominio e non sia stato alterato. Obbligatori: la verifica dipende da tutti e tre.
Return path	MX	send	feedback-smtp.<region>.amazonses.com, priorità 10	Riceve le notifiche di rimbalzo e di reclamo indirizzate a send.acme.com. Insieme al record TXT qui sotto forma un dominio MAIL FROM personalizzato.
Return path	TXT	send	v=spf1 include:amazonses.com ~all	SPF per il sottodominio del return path. Poiché il mittente della busta è sul tuo dominio, SPF risulta allineato con il tuo indirizzo From, come richiede DMARC.
DMARC (consigliato)	TXT	_dmarc	v=DMARC1; p=none;	Indica ai destinatari che cosa fare con le email che non superano l’autenticazione ed è richiesto da Gmail e Yahoo ai mittenti di massa. Vedi DMARC.

Virgolette nei TXT

L’API mostra i valori TXT racchiusi tra virgolette ("v=spf1 ..."). La maggior parte delle dashboard DNS aggiunge le virgolette da sola; inserisci il valore senza.

Nota

Il sottodominio send può essere rinominato con custom_return_path quando aggiungi il dominio. Vedi Return path personalizzato.

Stai costruendo una piattaforma che invia per i tuoi clienti? Passa tenant_id (un id di tenant o il tuo external_id) per rendere il dominio di proprietà del tenant; le email inviate da quel dominio vengono poi attribuite automaticamente a quel tenant. Vedi Modalità piattaforma.

Stati

Stato	Significato
not_started	Dominio aggiunto, DNS non ancora rilevato.
pending	SpacePost sta controllando il DNS.
verified	DKIM è confermato. Puoi inviare da questo dominio.
temporary_failure	Una ricerca è fallita temporaneamente. Viene ritentata automaticamente.
failed	Il DNS non è stato trovato entro 72 ore, oppure un record è sbagliato. Correggi i record e richiama verify.

Il dominio è verified non appena DKIM viene superato. Se mancano solo i record del return path, le email vengono comunque inviate, ma l’allineamento SPF ripiega sul dominio di Amazon, il che indebolisce l’allineamento DMARC. Correggilo per ottenere il miglior recapito.

Ogni record in records ha un proprio status con gli stessi valori, così puoi vedere esattamente quale manca.

Inviare da sottodomini

Se acme.com è verificato puoi inviare da qualsiasi sottodominio (news@mail.acme.com). Verificare il sottodominio stesso (mail.acme.com) è la pratica migliore per le email di marketing, perché mantiene la reputazione separata da quella del dominio transazionale.

Limiti

Piano	Domini
Free	3
Pro	10
Scale	1.000

Aggiungere un dominio già registrato da un altro team restituisce 422 validation_error (“Domain already registered”).

Guide per provider DNS

Cloudflare

AWS Route 53

Vercel

Namecheap

GoDaddy

Google Domains / Squarespace

DigitalOcean

Hetzner

Sei bloccato? Vedi Risoluzione dei problemi.