Domaines d’envoi

Domaines d’envoi

Ajoutez un domaine ou un sous-domaine que vous contrôlez, puis publiez chez votre hébergeur DNS les enregistrements que renvoie l’API. Rien n’est placé sur votre domaine principal : votre propre courrier et votre enregistrement SPF restent intacts.

const { data: domain, error } = await honkio.domains.create({ domain: 'mail.acme.ca' })
if (error) throw new Error(error.message)
for (const record of domain.records) console.log(record.type, record.name, record.value)

curl -X POST https://api.honkio.ca/v1/email-domains \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "mail.acme.ca" }'

// Publish the returned records at your DNS host, then check them:
const { data, error } = await honkio.domains.verify('DOMAIN_ID')
if (error) throw new Error(error.message)
console.log(data.status, data.verified, data.missing) // verified true []

# Publish the returned records at your DNS host, then check them:
curl -X POST https://api.honkio.ca/v1/email-domains/DOMAIN_ID/verify \
  -H "Authorization: Bearer mk_live_YOUR_KEY"
# → { "status": "verified", "verified": true, "missing": [] }

// Tracking per domain (null = the platform default):
const { data, error } = await honkio.domains.update('DOMAIN_ID', { openTracking: false, clickTracking: null })
if (error) throw new Error(error.message)
console.log(data.open_tracking, data.click_tracking)

# Tracking per domain (null = the platform default):
curl -X PATCH https://api.honkio.ca/v1/email-domains/DOMAIN_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "open_tracking": false, "click_tracking": null }'

Un domaine est en attente tant que ses enregistrements sont introuvables, en vérification pendant leur propagation, et vérifié quand DKIM, le MX, SPF et le fournisseur de courriel concordent. Il passe à échoué quand ses enregistrements sont encore manquants après 7 jours ou que le fournisseur de courriel rejette carrément le domaine, et à temporairement échoué après une défaillance passagère du fournisseur, ou quand un domaine déjà vérifié échoue à une nouvelle vérification ; appelez verify de nouveau une fois les enregistrements corrigés. La vérification est refaite chaque jour ; si un enregistrement disparaît, le domaine a 72 heures pour se rétablir avant de cesser d’envoyer.

Appelez verify à tout moment pour vérifier sur-le-champ. La réponse nomme tout enregistrement encore manquant.

Un domaine appartient à qui prouve qu’il contrôle son DNS. Le domaine vérifié d’un autre compte ne peut pas être ajouté ; une revendication non vérifiée bloque les autres pendant 72 heures, et la réponse 409 EMAIL_DOMAIN_IN_USE indique quand elle expire.

Un compte peut détenir 5 domaines d’envoi par défaut. Un domaine dont la vérification a échoué ne compte pas, ni un domaine ajouté avec une clé de test. Demandez au soutien d’augmenter la limite ; une fois la limite atteinte, l’API répond 422 EMAIL_DOMAIN_LIMIT_REACHED à l’ajout d’un domaine, et à la vérification d’un domaine en échec dont le DNS est maintenant correct (il reste en échec).

Le suivi des ouvertures et des clics est désactivé par défaut. Activez-le par domaine avec PATCH, ou par courriel avec le champ tracking ; null rétablit la valeur par défaut de la plateforme.

Une clé API peut être restreinte à certains domaines d’envoi dès sa création. Une clé restreinte ne peut envoyer que depuis ses propres domaines, et ne peut reprogrammer ou annuler qu’un courriel envoyé depuis l’un d’eux ; l’ajout, la vérification et la gestion des domaines eux-mêmes ne sont pas touchés et restent ouverts à toute clé disposant de la permission email_domains.