Documentation
Sign inGet started
Commencer
Guides
Référence API
SDK
CLI
Base de connaissances
Changelog

Envoyer des e-mails via SMTP

Si votre application prend déjà en charge SMTP, dirigez-la vers notre relais en modifiant l'hôte, le port et les identifiants. Les frameworks, systèmes de gestion de contenu, imprimantes et autres logiciels capables de soumettre du courrier à un relais SMTP peuvent utiliser cette méthode.
Le courrier soumis via SMTP est traité exactement comme le courrier envoyé via l'API e-mail : même vérification de domaine, mêmes pools d'IP, même signature DKIM, même gestion des suppressions, même suivi, mêmes événements et mêmes analyses. SMTP est une seconde voie d'accès au même produit : tout ce que vous configurez pour l'un s'applique à l'autre.
Choisissez le service de relais SMTP si vous souhaitez conserver le code de construction de messages existant de votre application. Choisissez l'API e-mail si vous avez besoin de champs de requête structurés ou de modèles enregistrés. SMTP prend le contenu du message MIME et les options d'envoi de la configuration de la clé API.

Ce dont vous avez besoin au préalable

  • Un domaine d'envoi vérifié. L'adresse que vous indiquez dans MAIL FROM (et l'en-tête From du message) doit appartenir à un domaine que vous avez vérifié dans cet espace de travail. Voir Domaines d'envoi.
  • Une clé API avec le scope emails. SMTP utilise vos clés API habituelles et ne nécessite pas d'identifiant SMTP séparé. Créez une clé dans Developers > Clés API avec l'envoi d'e-mails activé. Une clé sans le scope emails ne peut pas envoyer, et une clé verify seule non plus.

Paramètres de connexion

Dirigez votre client vers l'hôte SMTP correspondant à la région de votre clé. La région est le préfixe de la clé elle-même : une clé bk_eu1_... envoie via l'hôte eu1, une clé bk_us1_... via us1. S'authentifier avec une clé de l'autre région échoue avec une réponse 535 indiquant l'hôte à utiliser.
RégionHôte
EUeu1.smtp.bird.com
USus1.smtp.bird.com
PortChiffrement
465TLS implicite (SMTPS)
587STARTTLS
2525STARTTLS
Utilisez celui que votre client prend en charge :
  • Port 465, TLS implicite (SMTPS). La connexion est chiffrée dès le premier octet, avant l'envoi de toute commande. Dans la plupart des bibliothèques, il s'agit de l'option "SSL/TLS" ou "SMTPS".
  • Ports 587 et 2525, STARTTLS. La connexion s'ouvre en clair et passe en TLS via la commande STARTTLS avant l'authentification. Il s'agit de l'option "STARTTLS", parfois simplement intitulée "TLS". Choisissez 2525 si votre réseau bloque le port 587.
Dans les deux cas, la session est chiffrée avant l'envoi de vos identifiants, qui ne transitent donc jamais en clair : sur les ports 587 et 2525, AUTH est refusé tant que STARTTLS n'a pas été exécuté. Le port 25 n'est pas proposé pour la soumission.

Authentification

Authentifiez-vous avec AUTH PLAIN ou AUTH LOGIN. Le nom d'utilisateur est la chaîne littérale bird et le mot de passe est votre clé API :
Exemple de code
Username: bird
Password: bk_eu1_your_api_key
Le nom d'utilisateur est un littéral fixe sans identité propre. C'est la clé API dans le champ mot de passe qui authentifie. Dans la plupart des outils SMTP, vous collez votre clé API dans le champ mot de passe et définissez le nom d'utilisateur sur bird. Révoquer la clé coupe son envoi SMTP en quelques secondes, y compris en cours de connexion.

Ce qui vient du message et ce qui vient de la configuration de la clé

Tout ce qui a une place naturelle dans un message MIME provient du message lui-même : les en-têtes From, To, Cc et Reply-To, l'objet, les corps HTML et texte, ainsi que les pièces jointes et images en ligne. Les destinataires sont extraits de l'enveloppe SMTP (RCPT TO). Une adresse dans RCPT TO qui ne figure pas dans un en-tête To ou Cc visible est traitée comme Bcc. Un message peut avoir au maximum 50 destinataires (to, cc et bcc confondus) et sa taille totale est limitée à 20 Mo.
Les options d'envoi qui n'ont pas de place standard dans un message MIME proviennent de la configuration SMTP de la clé. Elles incluent le pool d'IP, la catégorie, les tags, ainsi que le suivi des ouvertures et des clics. Une clé non configurée utilise le pool par défaut de votre organisation, la catégorie transactional et le suivi activé. Configurez la clé dans Email > SMTP, ou appelez l'API de config SMTP. Attribuez à chaque application sa propre clé lorsqu'elle nécessite des valeurs par défaut différentes. Les modifications s'appliquent aux nouveaux messages sans reconnecter le client.

Une session complète

Sur le port 465, le client ouvre d'abord la connexion TLS, puis exécute l'intégralité du dialogue SMTP à l'intérieur :
Exemple de code
   ... TLS handshake ...
S: 220 eu1.smtp.bird.com ESMTP Service Ready
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-AUTH PLAIN LOGIN
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: AUTH PLAIN <base64 of bird + key>
S: 235 2.0.0 Authentication succeeded
C: MAIL FROM:<news@yourdomain.com>
C: RCPT TO:<delivered@messagebird.dev>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_01ky7ma8y2es1s2akzk53tmjn0
Sur le port 587 ou 2525, le client se connecte en clair, émet STARTTLS pour passer la connexion en mode chiffré, puis exécute le même dialogue à l'intérieur de TLS. AUTH n'est pas proposé tant que la mise à niveau n'est pas terminée :
Exemple de code
S: 220 eu1.smtp.bird.com ESMTP Service Ready
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-STARTTLS
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: STARTTLS
S: 220 2.0.0 Ready to start TLS
   ... TLS handshake ...
C: EHLO myapp
S: 250-Hello myapp
   250-PIPELINING
   250-8BITMIME
   250-ENHANCEDSTATUSCODES
   250-CHUNKING
   250-AUTH PLAIN LOGIN
   250-SIZE 20971520
   250 LIMITS RCPTMAX=50
C: AUTH PLAIN <base64 of bird + key>
S: 235 2.0.0 Authentication succeeded
C: MAIL FROM:<news@yourdomain.com>
C: RCPT TO:<delivered@messagebird.dev>
C: DATA
   ... your MIME message ...
C: .
S: 250 2.0.0 Ok: queued as em_01ky7ma8y2es1s2akzk53tmjn0
La réponse finale 250 renvoie l'ID du message mis en file d'attente, le même ID em_... que vous obtiendriez via l'API. Vous pouvez rechercher le message par cet ID dans le journal des e-mails ou via GET /v1/email/messages/{message_id}.

Réessayer en toute sécurité

Le pipeline accepte un message et le distribue de manière asynchrone, et les clients SMTP réessaient de manière agressive lorsqu'une connexion est interrompue. Pour sécuriser une nouvelle tentative, ajoutez un en-tête X-Bird-Idempotency-Key au message : une répétition dans la fenêtre de rétention renvoie l'ID du message déjà mis en file d'attente au lieu d'envoyer un second exemplaire. Utilisez une valeur stable pour le message logique, comme un ID de commande ou un ID de notification. Évitez de générer une valeur aléatoire à chaque tentative.
Conservez l'ID du message mis en file d'attente avec l'événement applicatif à l'origine de l'envoi. Si la connexion est interrompue avant la réception de la réponse finale, réessayez ce message logique avec la même clé. Après la fenêtre de rétention, une nouvelle tentative peut créer un autre message. Conservez votre propre historique d'envoi pour la reprise au-delà de cette fenêtre.

Limites de connexion

Chaque organisation peut maintenir jusqu'à 10 connexions SMTP authentifiées simultanées par défaut. Une connexion est comptée de l'authentification jusqu'à sa fermeture, tous serveurs et clés API de l'organisation confondus. À la limite, une connexion supplémentaire reçoit une réponse transitoire 421 après l'authentification. Réutilisez les connexions, réduisez la concurrence et réessayez. La limite compte les connexions ouvertes indépendamment du volume de messages. Email > SMTP affiche les connexions actives par rapport à la limite.
Dimensionnez votre pool de connexions en fonction du plafond de connexions de l'organisation. Réglez le rythme des soumissions en fonction des quotas d'envoi. Les en-têtes de limitation du débit HTTP décrivent les requêtes API ; ils ne constituent pas une allocation de débit d'envoi SMTP.

Gérer les réponses SMTP

SMTP signale un domaine d'envoi non vérifié, un domaine de destinataire réservé, un pool d'IP inutilisable, un type de pièce jointe bloqué ou un message malformé par une réponse permanente 550. Un message dépassant la limite de 20 Mo renvoie 552. Un quota d'envoi dépassé ou un nombre de destinataires supérieur à 50 renvoie une réponse transitoire 452. Les destinataires supprimés sont traités de manière asynchrone : SMTP accepte le message, puis chaque destinataire supprimé apparaît comme rejected dans le journal des e-mails et les événements.
Pour le choix de l'interface, comparez la soumission et la reprise SMTP et HTTP. Les deux méthodes mettent le travail en file d'attente avant la distribution au destinataire. Un événement email.delivered enregistre l'acceptation par le serveur de réception. Cet événement n'établit pas le placement en boîte de réception.

Étapes suivantes

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 emailExplorer la fonctionnalitéEmailSuivre le parcours d'apprentissageBuild your first integrationGuide d'implémentationSend your first email
Essayez la pratique et obtenez un guide d'implémentation