Domaines d'envoi

Avant que nous puissions envoyer des e-mails depuis votre domaine, vous devez prouver que vous en êtes propriétaire et publier les enregistrements DNS qui permettent aux fournisseurs de messagerie d'authentifier vos messages. Un domaine d'envoi est la ressource rattachée à l'espace de travail (dom_...) qui suit cette configuration : quels enregistrements publier, lesquels ont été vérifiés, et si le domaine est prêt à envoyer.

Partager un domaine entre organisations

Un même domaine peut être enregistré par plusieurs organisations sans qu'elles interfèrent entre elles. Chaque organisation prouve la propriété avec sa propre clé DKIM, donc :

Une autre organisation sur le même domaine ne peut jamais voir votre état de vérification ni modifier votre configuration.
Chaque région (us1, eu1) est indépendante : le même domaine dans deux régions correspond à deux enregistrements distincts avec leurs propres enregistrements DNS. Enregistrez-le dans chaque région depuis laquelle vous envoyez.

Enregistrer un domaine

Créez le domaine avec POST /v1/email/domains. L'appel est rattaché à l'espace de travail et prend le domaine d'envoi ainsi que des libellés optionnels pour les noms d'hôte de return-path et de tracking. Passez uniquement le libellé (send, links), et nous composons le nom d'hôte complet sous votre domaine d'envoi. Les valeurs omises prennent par défaut send et links.

Utilisez un sous-domaine dédié (mail.acme.com) plutôt que votre domaine enregistré. Cela isole votre réputation d'envoi de tout le reste du domaine et maintient tous les enregistrements que nous vous demandons de publier hors de l'apex de votre zone. Cette seconde raison est celle qui pose problème : l'enregistrement MX pour la réception se place au même nom que les enregistrements MX qui acheminent déjà le courrier de votre entreprise, donc sur un domaine d'envoi apex, le publier redirige ce courrier vers nous.

const domain = await bird.domains.create({ domain: "mail.acme.com" });
console.log(domain.id, domain.status); // "dom_…", "pending"

domain = client.domains.create(domain="mail.acme.com")
print(domain.id, domain.status)

domain, err := client.Domains.Create(context.Background(), bird.DomainCreateParams{
	Domain: "mail.acme.com",
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(domain.Id, *domain.Status)

$domain = $bird->domains->create(
    (new DomainCreate())->setDomain('mail.acme.com'),
);
echo $domain->getId(), ' ', $domain->getStatus(); // "dom_…", "pending"

bird email domains create mail.acme.com

{
  "name": "email_domains_create",
  "arguments": {
    "domain": "mail.acme.com"
  }
}

curl -s https://eu1.platform.bird.com/v1/email/domains \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "mail.acme.com",
    "return_path": { "name": "send" },
    "tracking": { "name": "links" }
  }'

La réponse inclut status: pending, le sélecteur DKIM attribué à votre organisation, et les dns_records à publier. Un enregistrement d'espace de travail existant renvoie 409. Un dépassement du quota de domaines de votre organisation renvoie 422. Remplacez eu1 par us1 pour un espace de travail US. Les clés API utilisent les mêmes préfixes régionaux : bk_eu1_... et bk_us1_.... Vous pouvez aussi gérer les domaines dans Email > Domains.

La page Domains dans le tableau de bord, montrant un domaine d'envoi vérifié avec ses capacités d'envoi, de return-path et de tracking

Publier les enregistrements DNS

Le tableau dns_records vous fournit les name, host et value prêts à copier-coller pour chaque enregistrement. Certains fournisseurs rejettent une longue valeur TXT DKIM en une seule chaîne ; le découpeur d'enregistrements DNS la divise en chaînes entre guillemets attendues par ces fournisseurs. Ce que vous publiez :

Enregistrement	Type	Requis pour l'envoi	Rôle
DKIM	TXT	Oui	Prouve la propriété et signe vos messages avec la clé de votre organisation
CNAME return-path	CNAME	Oui	Achemine les rebonds vers nous et couvre SPF ; la recherche SPF suit le CNAME, donc aucun enregistrement SPF sur l'apex de votre domaine n'est nécessaire
DMARC	TXT	Oui	Toute politique v=DMARC1 valide couvrant le domaine d'envoi, sur le domaine lui-même ou sur son domaine enregistré (organisationnel). Une politique p=none minimale suffit.
CNAME tracking	CNAME	Non	Active les noms d'hôte de suivi d'ouverture/clic personnalisés ; les liens suivis sont servis via HTTPS une fois vérifié
MX entrant	MX	Non	Achemine le courrier du domaine vers nous pour la réception. Porte optional: true tant que vous n'activez pas la réception ; le publier remplace les enregistrements MX actuels du domaine.

Pour le rôle et les valeurs de chaque enregistrement, consultez DKIM, SPF et DMARC. Les enregistrements MX de réception sont dans dns_records avec purpose: inbound_mx chaque fois que la réception est disponible dans votre région, et ils portent optional: true jusqu'à ce que vous activiez la réception sur le domaine. Ignorez tout enregistrement marqué optional sauf si vous souhaitez ce qu'il active. Pour les étapes de configuration par fournisseur DNS, consultez les guides Cloudflare, Route 53 ou registraire générique.

Le tableau de bord détecte les fournisseurs DNS pris en charge à partir des serveurs de noms de votre domaine et renvoie vers leurs paramètres DNS. Ouvrez Email > Domains, puis sélectionnez un domaine pour afficher ses enregistrements. Si quelqu'un d'autre gère votre DNS, POST /v1/email/domains/{domain_id}/dns-records/share lui envoie par e-mail les enregistrements à publier.

La page DNS Records d'un domaine dans le tableau de bord, montrant l'enregistrement DKIM vérifié avec le nom et la valeur copiables, suivi des sections return-path et DMARC

Cycle de vérification

Un nouveau domaine commence à l'état pending. Vous n'avez jamais besoin de faire du polling car nous vérifions vos enregistrements automatiquement. Les vérifications démarrent immédiatement à l'enregistrement et s'espacent de quelques minutes à une heure au cours des trois premiers jours. Elles s'exécutent ensuite quotidiennement pour chaque domaine actif. Publier vos enregistrements et attendre suffit ; la plupart des domaines sont vérifiés quelques minutes après la propagation DNS. Si vous souhaitez une vérification immédiate (par exemple juste après avoir modifié le DNS), appelez POST /v1/email/domains/{domain_id}/verify : il exécute une vérification à jour et renvoie le domaine mis à jour. Un 200 avec des enregistrements encore pending n'est pas un échec ; cela signifie que les enregistrements n'ont pas encore été trouvés, ce qui est normal pendant la propagation DNS (de quelques minutes à quelques heures). L'appel peut être répété sans risque pendant l'attente.

Un domaine qui reste non vérifié pendant environ 14 jours est supprimé. Nous envoyons un rappel par e-mail à l'espace de travail quelques jours avant la suppression pour que vous puissiez terminer la configuration.

Le status de premier niveau du domaine reflète la propriété, prouvée par l'enregistrement DKIM :

pending : l'enregistrement DKIM n'a pas encore été publié.
verified : l'enregistrement DKIM est en place ; la propriété est confirmée.
failed : un enregistrement DKIM existe mais ne correspond pas à la valeur attendue, ou un enregistrement précédemment vérifié a été supprimé. Corrigez l'enregistrement pour rétablir la vérification.
temporary_failure : la résolution DNS a échoué de manière transitoire ; la vérification est réessayée automatiquement.
rejected : le domaine a été refusé pour des raisons de politique ; contactez le support.

La capacité d'envoi est signalée séparément sous capabilities. La porte d'envoi est capabilities.sending, qui ne se vérifie que lorsque DKIM, le CNAME return-path et une politique DMARC sont tous en place ; SPF à l'apex du domaine n'est pas requis. La disponibilité du tracking (capabilities.tracking) est indépendante de la porte d'envoi : elle contrôle si le suivi d'ouverture/clic personnalisé peut être utilisé, jamais si le domaine peut envoyer.

Quand un enregistrement vérifié casse

La vérification ne s'arrête jamais : la revérification quotidienne surveille les domaines vérifiés, donc si votre DNS casse par la suite, nous le détectons. Pour éviter les basculements intempestifs sur des incidents DNS transitoires, un enregistrement vérifié qui commence à échouer à ses revérifications est maintenu vérifié dans un état d'avertissement et revérifié toutes les heures, et nous vous notifions. Ce n'est qu'après 24 heures d'échecs continus que le domaine est rétrogradé ; toute vérification réussie dans cette fenêtre annule l'avertissement. Les rétrogradations prennent effet au prochain envoi, et un domaine rétrogradé se revérifie automatiquement une fois les enregistrements corrigés, lors de la prochaine vérification automatique ou d'une vérification manuelle.

Gestion des domaines

Régions. L'état du domaine est régional. Si vous envoyez depuis us1 et eu1, enregistrez le domaine dans chaque région ; chaque enregistrement obtient son propre sélecteur DKIM et se vérifie indépendamment.

Modification des noms d'hôte return-path ou tracking. Ces noms d'hôte appartiennent à la configuration de domaine de votre espace de travail. Un nom d'hôte déjà vérifié n'est jamais remplacé par un non vérifié : les modifications sont mises en attente, vérifiées en parallèle de votre configuration active, et promues uniquement une fois les nouveaux enregistrements validés.

Suivi d'ouverture/clic. Les bascules settings appartiennent à la configuration de domaine de l'espace de travail. Les modifications des bascules s'appliquent uniquement à cette configuration de domaine. Vous pouvez les activer dès qu'un domaine de tracking est configuré. En activer une sans domaine de tracking renvoie une 409. Les bascules n'affectent les envois qu'après la vérification de ce domaine de tracking, donc la vérification est appliquée par envoi.

Suppression. DELETE /v1/email/domains/{domain_id} supprime le domaine d'envoi de votre espace de travail. Les autres usages du domaine restent inchangés.

Étapes suivantes

DKIM, SPF et DMARC : le rôle de chaque enregistrement et comment choisir les valeurs.
Guides DNS par fournisseur : étapes de configuration pour Cloudflare, Route 53, GoDaddy et plus.
Référence API des domaines : schémas de requête/réponse complets pour chaque endpoint.

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Regarder le guideGetting started with email Explorer la fonctionnalitéEmail Suivre le parcours d'apprentissageBuild your first integration Guide d'implémentationSend your first email

Essayez la pratique et obtenez un guide d'implémentation