Envoyer un e-mail

Bêta

Fonctionnalité en cours de déploiement. L'interface décrite ici est celle de la prochaine livraison : elle peut encore évoluer, et n'est pas forcément activée sur votre tenant.

Les e-mails sont envoyés à partir de gabarits que vous déclarez : aucun message libre.

Votre tenant peut envoyer des e-mails transactionnels (bienvenue, notification, confirmation) depuis ses API générées et depuis la console. Trois objets du groupe mail.stackngo.io décrivent l'envoi : un fournisseur (le compte SMTP), un expéditeur (l'adresse From) et un gabarit (sujet et corps).

Prérequis

Une session sur votre tenant (sng tenant use acme) et le droit mail:write pour déclarer, mail:send pour envoyer (policies gérées readwrite ou admin).
Un compte SMTP chez votre hébergeur de messagerie (port 465 ou 587, TLS) et son mot de passe, déposé dans un secret de votre tenant.
L'accès à la zone DNS du domaine d'envoi.

1. Déclarer le fournisseur, l'expéditeur et le gabarit

mail.yml
apiVersion: mail.stackngo.io/v1alpha1
kind: MailProvider
metadata:
  name: principal
spec:
  host: smtp.exemple.fr
  port: 587
  tls:
    mode: starttls
  auth:
    username: notifications@exemple.fr
    passwordSecretRef:
      name: smtp-principal
---
apiVersion: mail.stackngo.io/v1alpha1
kind: MailUser
metadata:
  name: notifications
spec:
  address: notifications@exemple.fr
  providerRef:
    name: principal
---
apiVersion: mail.stackngo.io/v1alpha1
kind: MailTemplate
metadata:
  name: bienvenue
spec:
  lang: fr
  subject: "Bienvenue {{.Prenom}}"
  text: "Bonjour {{.Prenom}}, votre compte est prêt."
  variables:
    - name: Prenom
      example: Camille

sng apply mail.yml

Le même résultat s'obtient dans la console, page E-mails : onglets Fournisseurs, Gabarits et Expéditeurs.

2. Vérifier le domaine d'envoi

Un expéditeur n'envoie qu'une fois son domaine vérifié. Dans la console, ouvrez l'expéditeur : la page liste les enregistrements DNS à publier, avec leur état.

Contrôle	Ce qu'il faut
Propriété	Un enregistrement `TXT` indiqué par la console, sauf si le domaine est déjà dans une zone de votre tenant
SPF	Un enregistrement qui autorise votre fournisseur
DMARC	Un enregistrement `_dmarc` (la console propose une valeur)
DKIM	Les sélecteurs de votre fournisseur, s'ils sont déclarés dans `domainAuth`

Publiez-les dans votre zone (voir Enregistrements), puis cliquez sur Vérifier. L'expéditeur est prêt quand sa condition Ready vaut True.

3. Envoyer un e-mail de test depuis la console

Sur l'expéditeur prêt, Envoyer un e-mail de test envoie un message d'essai à une adresse de votre choix. La liste Derniers envois montre le statut de chaque message (en attente, envoyé, échoué) et un code d'erreur le cas échéant. Elle ne montre jamais le corps du message.

4. Envoyer depuis une API générée

Dans la GeneratedAPI, désignez l'expéditeur et les gabarits que l'API a le droit d'utiliser :

spec:
  mail:
    senderRef: notifications      # nom d'un MailUser de votre tenant
    templates: [bienvenue]        # noms de MailTemplate de votre tenant

L'API n'envoie que ces gabarits depuis cet expéditeur. Tant que l'expéditeur ou un gabarit n'est pas prêt, la GeneratedAPI reste Synced=False avec la raison MailNotReady.

Un envoi donne le gabarit, l'expéditeur, les destinataires et la valeur de chaque variable :

{
  "template": "bienvenue",
  "from": "notifications",
  "to": ["camille@exemple.fr"],
  "variables": {"Prenom": "Camille"}
}

La réponse indique que le message est pris en charge (queued). Envoyer deux fois avec le même en-tête Idempotency-Key ne produit qu'un message.

Limites

Limite	Valeur
Destinataires par message	50
Messages par heure vers une même adresse	10
Débit d'un fournisseur	`limits.perMinute` (60 par défaut, 120 au plus)
Fournisseurs par tenant	5
Taille d'une valeur de variable	4 Kio

Au-delà, l'envoi est refusé avec une erreur rate_limited ou quota_exceeded et un délai avant de réessayer.

Dépannage

Constat	Cause probable
Envoi refusé, `sender_not_ready`	Le domaine n'est pas vérifié ou le fournisseur n'est pas `Ready`
`Reachable=False`, catégorie `auth`	Identifiant ou mot de passe refusé par le serveur SMTP
`Reachable=False`, catégorie `tls`	Mauvais couple port/mode (465 avec `implicit`, 587 avec `starttls`) ou certificat invalide
`template_invalid`	Variable utilisée mais non déclarée, ou l'inverse : lisez la condition `Valid` du gabarit
`forbidden`	Il manque le droit `mail:send` sur l'expéditeur ou le gabarit

Prérequis​

1. Déclarer le fournisseur, l'expéditeur et le gabarit​

2. Vérifier le domaine d'envoi​

3. Envoyer un e-mail de test depuis la console​

4. Envoyer depuis une API générée​

Limites​

Dépannage​

Pour aller plus loin​