Ajouter et vérifier un domaine

Pour envoyer depuis hello@acme.com, vous prouvez que vous possédez acme.com en publiant des enregistrements DNS. La vérification met en place la signature DKIM (pour que les destinataires sachent que le message vient bien de vous) et un return path personnalisé (pour que SPF et DMARC s’alignent sur votre domaine).

Avant d'ajouter un domaine

Les nouvelles équipes remplissent d’abord un court profil d’envoi, et certains domaines sont refusés (fournisseurs de messagerie gratuits, domaines enregistrés depuis moins de 7 jours). Voir Vérification du compte et limites d’envoi.

1. Ajouter le domaine

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

   Vous pouvez aussi utiliser le tableau de bord ou spacepost domains add acme.com.

2. Créer les enregistrements DNS

   La réponse contient un tableau records et un tableau 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;\"" }
     ]
   }

   Ajoutez-les chez votre fournisseur DNS. Voir les enregistrements expliqués ci-dessous et les guides par fournisseur.

3. Vérifier

   Les modifications DNS peuvent prendre quelques minutes (rarement des heures). SpacePost revérifie automatiquement les domaines en attente, et vous pouvez déclencher une vérification à tout moment :

   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

Les enregistrements expliqués

Dans l’API, les noms d’enregistrement sont relatifs à votre domaine (send, _dmarc, a1b2c3d4e5f6._domainkey). Certains fournisseurs DNS veulent le nom complet (send.acme.com) ; les guides par fournisseur indiquent lesquels.

Enregistrement	Type	Nom	Valeur	Rôle
DKIM (x3)	CNAME	<token>._domainkey	<token>.dkim.amazonses.com	Publie les clés publiques qu’Amazon SES fait tourner pour vous (« Easy DKIM »). Les destinataires s’en servent pour vérifier que chaque message a été signé par votre domaine et n’a pas été modifié. Obligatoire : la vérification dépend des trois.
Return path	MX	send	feedback-smtp.<region>.amazonses.com, priorité 10	Reçoit les notifications de rebond et de plainte adressées à send.acme.com. Avec le TXT ci-dessous, il forme un domaine MAIL FROM personnalisé.
Return path	TXT	send	v=spf1 include:amazonses.com ~all	SPF du sous-domaine de return path. Comme l’expéditeur de l’enveloppe est sur votre domaine, SPF s’aligne sur votre adresse From, ce dont DMARC a besoin.
DMARC (recommandé)	TXT	_dmarc	v=DMARC1; p=none;	Indique aux destinataires quoi faire des messages qui échouent à l’authentification, et est exigé par Gmail et Yahoo pour les expéditeurs en masse. Voir DMARC.

Guillemets des TXT

L’API affiche les valeurs TXT entre guillemets ("v=spf1 ..."). La plupart des interfaces DNS ajoutent elles-mêmes les guillemets ; saisissez la valeur sans eux.

Note

Le sous-domaine send peut être renommé avec custom_return_path lors de l’ajout du domaine. Voir Return path personnalisé.

Vous construisez une plateforme qui envoie pour vos propres clients ? Passez tenant_id (un id de tenant ou votre external_id) pour que le domaine appartienne au tenant ; les e-mails qui en partent sont alors attribués automatiquement à ce tenant. Voir Mode plateforme.

Statuts

Statut	Signification
not_started	Domaine ajouté, DNS pas encore détecté.
pending	SpacePost vérifie le DNS.
verified	DKIM est confirmé. Vous pouvez envoyer depuis ce domaine.
temporary_failure	Une recherche DNS a échoué temporairement. Elle est retentée automatiquement.
failed	Le DNS n’a pas été trouvé en 72 heures, ou un enregistrement est incorrect. Corrigez les enregistrements et rappelez verify.

Le domaine est verified dès que DKIM réussit. Si seuls les enregistrements du return path manquent, les e-mails partent quand même, mais l’alignement SPF se rabat sur le domaine d’Amazon, ce qui affaiblit l’alignement DMARC. Corrigez-le pour une délivrabilité optimale.

Chaque enregistrement de records a son propre status avec les mêmes valeurs, ce qui vous permet de voir exactement lequel manque.

Envoyer depuis des sous-domaines

Si acme.com est vérifié, vous pouvez envoyer depuis n’importe quel sous-domaine (news@mail.acme.com). Vérifier le sous-domaine lui-même (mail.acme.com) est une meilleure pratique pour les e-mails marketing, car cela sépare la réputation de celle de votre domaine transactionnel.

Limites

Forfait	Domaines
Free	3
Pro	10
Scale	1 000

Ajouter un domaine qu’une autre équipe a déjà enregistré renvoie 422 validation_error (« Domain already registered »).

Guides par fournisseur DNS

Cloudflare

AWS Route 53

Vercel

Namecheap

GoDaddy

Google Domains / Squarespace

DigitalOcean

Hetzner

Bloqué ? Voir Dépannage.