IT & Engineering
Envoyer des emails avec Python3 et l’API de Mailgun
Si vous cherchez à simplifier votre approche de l’envoi d’emails de manière programmatique, vous êtes entre de bonnes mains. Notre équipe de développement a l’expérience dont vous avez besoin pour vous lancer. Poursuivez votre lecture pour découvrir en détail l’intégration de Python3 à la puissante email API de Mailgun, avec des informations, des conseils et des optimisations tout au long du processus.
Pour commencer : ce dont vous aurez besoin pour ce tutoriel
Pour l’envoi d’emails, deux options s’offrent à vous : manuelle ou programmatique. Quand on parle de les emails transactionnels en particulier, l’approche programmatique est la meilleure solution. Au lieu d’envoyer manuellement des notifications ou des mises à jour importantes par email, vous pouvez utiliser des scripts d’email automatisés pour gagner du temps et réduire les erreurs.
Les scripts (de petits programmes qui automatisent les tâches) offrent un moyen plus efficace de procéder à l’envoi d’emails en masse, de planifier des messages ou d’être appelés directement depuis votre application. L’envoi d’emails via des scripts automatisés comprend notamment les cas d’usage suivants :
- L’envoi d’emails de bienvenue lors de l’inscription d’utilisateurs
- L’envoi de notifications et d’alertes depuis des applications, comme informer la base d’utilisateurs de leur utilisation du service ou avertir l’équipe d’administration lorsque les ressources du serveur sont faibles
- L’envoi de rapports, tel qu’un rapport hebdomadaire sur la nouvelle clientèle
- L’envoi de campagnes de marketing, par exemple pour promouvoir de nouveaux produits ou services
Dans ce tutoriel, vous apprendrez à envoyer des emails à l’aide de scripts Python3 et de l’API de Mailgun.
Prérequis
Pour suivre ce tutoriel sur Python3 et l’email API, vous aurez besoin des éléments suivants :
- Python 3.9 ou supérieur. Python est souvent décrit comme le couteau suisse des langages de programmation, et il offre un large éventail de possibilités. Outre ses nombreuses autres utilisations, Python est idéal pour l’écriture de divers scripts.
- Un compte Mailgun. Mailgun est une plateforme d’envoi d’emails qui vous permet d’envoyer et de suivre des emails. Si vous n’utilisez pas encore Mailgun, vous pouvez suivre ce tutoriel en utilisant notre essai gratuit.
Configurer un nouveau projet Python
Commençons.
Commencez par créer un répertoire approprié pour votre projet Python et ajoutez-y un fichier .env vide. Avant de poursuivre, envisagez de créer et d’activer un nouvel environnement virtuel avant d’installer les bibliothèques Python requises pour ce tutoriel. Cela isole votre projet, ce qui évite tout conflit de dépendance.
Pour installer les bibliothèques nécessaires (requests et python-dotenv) en utilisant pip dans votre environnement virtuel, exécutez la commande suivante :
pip install requests python-dotenv
La bibliothèque requests vous permet d’effectuer des appels d’API, tandis que la bibliothèque python-dotenv vous permet de stocker la clé API en dehors de votre code.
Obtenir une clé API avec Mailgun
Ensuite, vous obtiendrez une clé API à partir de votre compte Mailgun, que vous utiliserez pour effectuer des appels d’API vers Mailgun.
Connectez-vous à votre compte Mailgun et créez une clé API depuis la page Sécurité de l’API, accessible via un menu déroulant situé sous votre nom, dans le coin supérieur droit.
Copiez et collez cette clé API dans le fichier .env de votre projet.
MAILGUN_API_KEY= »Votre clé API ici »
Pendant que vous êtes dans Mailgun, notez vos domaines d’envoi depuis le tableau de bord Mailgun.
Si vous bénéficiez d’un abonnement gratuit, vous verrez un domaine sandbox, qui sera utilisé dans le point de terminaison de l’API ainsi que pour l’adresse email d’expédition lors de l’envoi d’emails via l’API de Mailgun. Le domaine sandbox suit le format .mailgun.org, comme indiqué ci-dessous.
Vous devrez passer à un abonnement payant si vous souhaitez utiliser un domaine d’email personnalisé pour envoyer des emails via Mailgun. L’abonnement gratuit n’autorise que le domaine sandbox, et vous pouvez envoyer des emails à un maximum de cinq adresses vérifiées. Cependant, cet abonnement gratuit s’avère utile lors de la phase de développement pour l’intégration de l’API de Mailgun à votre système.
Importations et initialisation
Ensuite, créez le fichier main.py dans le répertoire de votre projet, puis copiez et collez ce code :
```python import jsonrnimport requestsrnimport loggingrnrnimport osrnfrom dotenv import load_dotenvrnrnlogging.basicConfig(level=logging.INFO) # set log levelrnload_dotenv() # for reading API key from `.env` file.rnrn# Sandbox API URL format: https://api.mailgun.net/v3/sandbox<ID>.mailgun.org/messagesrnMAILGUN_API_URL = "https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages"rnFROM_EMAIL_ADDRESS = "Sender Name <SENDER_EMAIL_ID>"
Il utilise la journalisation standard de Python et la configure au niveau INFO avec ce code :
```pythonrnlogging.basicConfig(level=logging.INFO)rn```
La fonction load_dotenv() provient de la bibliothèque python-dotenv et est utilisée pour charger les variables d’environnement à partir du fichier .env dans votre code Python. C’est une bonne pratique de stocker et de lire les informations sensibles, telles que les identifiants et les clés API, depuis le fichier .env.
MAILGUN_API_URL définit l’URL de l’API pour votre script Python, et indique l’identifiant email de l’expéditeur. Les deux doivent utiliser votre domaine d’envoi d’emails ou le domaine sandbox mentionné plus haut.
Envoyer des emails individuels à l’aide de l’API de Mailgun
Examinons d’abord la manière la plus simple d’utiliser l’API de Mailgun : l’envoi d’un email individuel. Vous pouvez l’utiliser pour des cas ponctuels, comme l’envoi d’un rappel ou d’un email de suivi à votre clientèle de grande valeur. Cela vous permettra également de suivre la livraison de l’email.
Copiez et collez le code ci-dessous dans votre fichier main.py, après les importations et l’initialisation :
```pythonrndef send_single_email(to_address: str, subject: str, message: str):rn try:rn api_key = os.getenv("MAILGUN_API_KEY") # get API-Key from the `.env` filernrn resp = requests.post(MAILGUN_API_URL, auth=("api", api_key),rn data={"from": FROM_EMAIL_ADDRESS,rn "to": to_address, "subject": subject, "text": message})rn if resp.status_code == 200: # successrn logging.info(f"Successfully sent an email to '{to_address}' via Mailgun API.")rn else: # errorrn logging.error(f"Could not send the email, reason: {resp.text}")rnrn except Exception as ex:rn logging.exception(f"Mailgun error: {ex}")rnrnif __name__ == "__main__":rn send_single_email("Manish <manish@exanple.com>", "Single email test", "Testing Mailgun API for a single email")rn```
Cette fonction send_single_email(…) prend trois arguments : to_address, subject et message. to_address correspond à une adresse email unique, et les deux autres correspondent à l’objet et au contenu de l’email.
Le code lit la clé API de Mailgun à partir du fichier .env et l’utilise pour effectuer un appel d’API, établissant ainsi une connexion sécurisée vers l’API_URL spécifiée. Cette clé API sert d’identifiant unique, permettant à Mailgun d’authentifier l’appel d’API et de vérifier qui utilise ses services.
Vous devez utiliser votre clé API unique pour garantir une authentification appropriée. L’adresse email d’expédition utilisée dans cet appel d’API doit également être associée à votre domaine valide ou au domaine sandbox de Mailgun. Dans le cas contraire, l’appel échouera et affichera un message d’erreur.
Les paramètres de données sont envoyés via la méthode HTTP POST au point de terminaison de l’API avec l’appel requests.post(…).
Lorsque l’appel d’API réussit, votre email est placé dans la file d’attente pour la livraison, et l’API renvoie un statut HTTP-200 (OK). En cas d’erreur, l’API renvoie un message d’erreur accompagné d’un code de statut HTTP approprié. Ces deux cas sont correctement enregistrés par cet extrait de code.
if __name__ == « __main__ » montre comment cette fonction peut être appelée dans votre script.
L’exécution de ce script dans votre terminal affichera ce qui suit :
Envoyer des emails en masse avec l’API de Mailgun
Bien que vous puissiez utiliser la fonction send_single_email(…) dans une boucle pour envoyer des emails à plusieurs destinataires, ce n’est pas la méthode la plus efficace en raison des délais d’E/S du réseau. Cette approche peut également se heurter à la limitation de débit de l’API.
Utilisez plutôt Envoi par lot pour l’envoi d’emails à plusieurs destinataires. L’extrait de code ci-dessous montre comment l’utiliser dans votre script Python.
Copiez et collez la fonction send_batch_emails(…) dans votre fichier main.py après la fonction send_single_email(…), et modifiez la partie __main__ comme indiqué ci-dessous :
```pythonrndef send_batch_emails(recipients: dict, subject: str, message: str):rn try:rn api_key = os.getenv("MAILGUN_API_KEY") # get API-Key from the `.env` filernrn to_address = list(recipients.keys()) # get only email addressesrn recipients_json = json.dumps(recipients) # for API callrnrn logging.info(f"Sending email to {len(to_address)} IDs...")rn resp = requests.post(MAILGUN_API_URL, auth=("api", api_key),rn data={"from": FROM_EMAIL_ADDRESS,rn "to": to_address, "subject": subject, "text": message,rn "recipient-variables": recipients_json})rn if resp.status_code == 200: # successrn logging.info(f"Successfully sent email to {len(recipients)} recipients via Mailgun API.")rn else: # errorrn logging.error(f"Could not send emails, reason: {resp.text}")rn except Exception as ex:rn logging.exception(f"Mailgun error: {ex}")rnrnif __name__ == "__main__":rn # send_single_email("Manish <manish@exanple.com>", "Single email test", "Testing Mailgun API for a single email")rn _recipients = {"manish@example.com": {"name": "Manish", "id": 1},rn "jakkie@example.com": {"name": "Jakkie", "id": 2},rn "elzet@example.com": {"name": "Elzet", "id": 3}}rnrn send_batch_emails(_recipients, "Hi, %recipient.name%!", "Testing Mailgun API. This email is sent via Mailgun API.")rn```
L’envoi par lot utilise un paramètre spécial appelé Variables de destinataire (Recipient Variables) qui vous permet d’envoyer des emails personnalisés à plusieurs destinataires via un appel d’API unique. L’utilisation des variables de destinataire avec l’envoi par lot garantit que Mailgun envoie des emails individuels à chaque destinataire du champ to. Sans cela, chaque destinataire verra les adresses email de tous les destinataires dans le champ to.
Voici un exemple de variable de destinataire, avec les adresses email comme clés et les « name » et « id » correspondants comme valeurs :
{« manish@example.com »: {« name »: « Manish », « id »: 1},
« jakkie@example.com »: {« name »: « Jakkie », « id »: 2},
« elzet@example.com »: {« name »: « Elzet », « id »: 3}}
La fonction send_batch_emails(…) possède trois paramètres : recipients, subject et message. Notez que recipients est un objet dictionnaire représentant la variable de destinataire mentionnée plus haut.
Le code extrait d’abord les adresses email de ce dictionnaire à l’aide de to_address = list(recipients.keys()), puis convertit le dictionnaire en JSON pour une utilisation par l’API avec l’appel recipients_json = json.dumps(recipients).
La variable recipients_json est transmise dans l’appel d’API pour le champ recipient-variables, qui est utilisé pour personnaliser l’objet et le contenu de l’email. L’objet est spécifié comme suit :
« Bonjour, %recipient.name% ! »
L’API de Mailgun remplace correctement le nom de chaque destinataire à partir du JSON lors de l’envoi d’emails avec %recipient.name%. Ainsi, dans l’exemple ci-dessus, Manish, Jakkie et Elzet recevront des objets d’email personnalisés : « Bonjour, Manish ! » « Bonjour, Jakkie ! » et « Bonjour, Elzet ! ». De même, vous pouvez personnaliser le contenu de l’email à l’aide de n’importe quelle valeur %recipient.KEY-NAME%.
Le reste du code de send_batch_emails(…) est similaire à la fonction send_single_email(…), à l’exception du fait qu’il envoie à plusieurs destinataires d’email via un appel d’API unique.
L’exécution de ce script affichera ce qui suit :
Voici un exemple de la façon dont cet email apparaîtra dans la boîte de réception du destinataire :
Fonctionnalités supplémentaires de l’API d’email de Mailgun
L’API de Mailgun offre plusieurs fonctionnalités supplémentaires pour vous faciliter la vie.
Envoi d’emails HTML avec pièces jointes
L’API de Mailgun vous permet d’ envoyer des emails avec des pièces jointes, que ce soit avec du contenu textuel ou HTML. Vous pouvez utiliser le même point de terminaison de l’API (https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages) avec une ‘attachment’ supplémentaire passée au paramètre files, comme indiqué ci-dessous :
```pythonrnfiles = {'attachment': open('weekly-report.csv', 'rb')} # file you want to attachrnresp = requests.post(MAILGUN_API_URL, auth=("api", api_key), files=files,rn data={"from": FROM_EMAIL_ADDRESS,rn "to": to_address, "subject": subject, "text": message})rn```
Livraison et suivi des emails
Mailgun propose un suivi détaillé des emails, notamment lorsque les emails sont livrés ou ouverts, que les liens sont cliqués, que les emails font l’objet de rebonds, que des désinscriptions ont lieu, et que les emails sont marqués comme spam. Ces données sont disponibles via le panneau de contrôle sur le tableau de bord et via l’API.
Mailgun sauvegarde également les emails de manière permanente s’ils ne peuvent pas être livrés (rebond permanent), ou si un destinataire se désinscrit ou marque l’email comme spam. Dans ces cas, Mailgun n’essaiera pas de renvoyer des emails à ces destinataires.
Modèles d’emails
L’API de Mailgun vous permet de créer des modèles HTML pour standardiser la mise en page de vos emails et les rendre plus attrayants grâce à des mises en page prédéfinies et du contenu standard.
Vous trouverez les modèles dans la barre latérale gauche, sous le menu Envoi (Sending).
Test des emails
Mailgun propose également des outils de test des emails pour vous assurer que vos messages ont l’apparence et les performances attendues. Avec Inspecter, vous pouvez vérifier automatiquement la présence de problèmes tels que des liens brisés, des images manquantes ou des déclencheurs de spam. Le Prévisualisation des emails vous permet de voir comment votre email s’affichera sur différents clients et appareils, tandis que Accessibilité des emails les tests permettent de confirmer que votre contenu est conforme aux normes d’accessibilité. Vous pouvez en savoir plus sur les outils de test des emails de Mailgun et intégrer ces vérifications dans votre flux de travail lors de la création d’emails avec l’API.
Bibliothèques d’email Python alternatives
Avant de faire appel à une API d’email dédiée, il est utile de connaître les outils natifs proposés par Python pour l’envoi d’emails, ainsi que quelques options tierces légères.
Python inclut deux modules principaux pour l’email basé sur SMTP : smtplib et email.
smtplib
Le module smtplib gère les sessions SMTP, ce qui vous permet de vous connecter à un serveur SMTP à l’aide de SMTP_SSL() pour le protocole TLS implicite (généralement le port 465) ou SMTP() avec starttls() pour le protocole TLS opportuniste (généralement le port 587). L’authentification est gérée à l’aide d’un nom d’utilisateur et d’un mot de passe standard.
Le package email est responsable de la construction du message. EmailMessage offre une API moderne de haut niveau, tandis que MIMEText et MIMEMultipart prennent en charge le texte brut, le HTML et les charges utiles en plusieurs parties.
Ce code génère un email simple et l’envoie de manière sécurisée via un serveur SMTP à l’aide de Python :
from email.message import EmailMessage
import smtplib
msg = EmailMessage()
msg["From"] = "you@example.com"
msg["To"] = "friend@example.com"
msg["Subject"] = "Hello"
msg.set_content("Sent with Python!")
with smtplib.SMTP("smtp.example.com", 587) as smtp:
smtp.starttls()
smtp.login("username", "password")
smtp.send_message(msg)
Yagmail
Plusieurs bibliothèques tierces permettent de réduire encore davantage le code passe-partout. Yagmail fournit une abstraction axée sur Gmail pour l’envoi de messages et de pièces jointes avec une configuration minimale. python-emails ajoute des fonctionnalités de plus haut niveau, telles que le rendu de modèles, la composition structurée de messages et la signature DKIM.
En règle générale, évitez de coder les identifiants en dur. Utilisez getpass() de Python pour une saisie sécurisée des mots de passe, stockez les clés API dans des variables d’environnement et transmettez toujours les emails sur des connexions chiffrées en TLS.
Authentification et sécurité
Il est important de garder à l’esprit certaines bonnes pratiques et astuces lorsque vous envoyez des emails de manière programmatique.
Gestion des erreurs
Lorsque votre script utilise une API tierce comme Mailgun pour envoyer des emails, vous devez gérer les erreurs potentielles liées aux défaillances du réseau ou de l’API ainsi que les réponses de l’API indiquant des erreurs, afin de garantir le bon fonctionnement de votre script, de détecter des problèmes tels que des clés API ou des URL non valides, et de savoir quand les emails ne sont pas envoyés par l’API de Mailgun. Sans gestion des erreurs, votre script risque d’échouer silencieusement, ce qui se traduirait par des emails non livrés.
Les extraits de code ci-dessus prévoient tous la gestion des erreurs susceptibles de se produire. Tout d’abord, ils vérifient le code de statut de la réponse (resp.status_code). Si la réponse n’est pas un succès (HTTP 200), ils enregistrent le message d’erreur afin que vous puissiez déboguer le problème.
Les fonctions send_single_email(…) et send_batch_emails(…) utilisent également un bloc try-except pour garantir que toutes les exceptions sont détectées et enregistrées correctement.
Délivrabilité des emails
La délivrabilité des emails consiste à s’assurer que vos emails atterrissent dans la boîte de réception du destinataire, et non dans son dossier spam. Vous avez besoin d’une bonne réputation d’expéditeur pour atteindre une délivrabilité élevée. Lorsqu’il s’agit de concevoir des envois programmatiques, nous pouvons examiner quelques éléments spécifiques pour améliorer la délivrabilité de vos emails, notamment l’authentification et l’optimisation des emails pour qu’ils soient responsifs.
Authentifier votre email
Utilisez SPF, DKIM et DMARC pour valider votre identité en tant qu’expéditeur. N’envoyez des emails qu’aux contacts vérifiés qui ont accepté de les recevoir et supprimez régulièrement les contacts inactifs et ceux qui marquent vos emails comme spam.
DMARC est en train de devenir une exigence dans le secteur. Découvrez pourquoi, et ce que fait cette norme d’authentification dans notre article sur la perspective de DMARC.
Commencer à envoyer des emails avec Python3 et l’API d’email de Mailgun
Dans cet article, vous avez appris à envoyer des emails à l’aide d’un script Python et de l’API de Mailgun. Vous avez également découvert les fonctionnalités de Mailgun, telles que le suivi des emails et les modèles, ainsi que l’importance de la gestion des erreurs, de l’optimisation de la délivrabilité et de l’envoi d’emails responsifs.
Les pros de l’email s’entraident. Vous pouvez trouver le code abordé dans ce tutoriel dans ce dépôt GitHub.
Cet article vous a-t-il été utile ? Si c’est le cas, n’hésitez pas à vous inscrire à notre newsletter pour recevoir d’autres tutoriels, annonces et informations sur le secteur.
FAQ
Utilisez TLS (STARTTLS) sur le port 587 lorsque vous souhaitez mettre à niveau une connexion simple vers une connexion chiffrée, et SSL (TLS implicite) sur le port 465 lorsque la connexion démarre de manière chiffrée.
- TLS (STARTTLS) : smtplib.SMTP(host, 587) → starttls() → login() → send_message()
- SSL (TLS implicite) : smtplib.SMTP_SSL(host, 465) → login() → send_message()
Dans les deux cas, construisez le message (par exemple avec EmailMessage) et envoyez-le avec smtp.send_message(msg). Authentifiez-vous toujours à l’aide des identifiants SMTP (nom d’utilisateur/mot de passe) fournis par votre fournisseur.
- EmailMessage : API moderne de haut niveau. Meilleur choix par défaut pour la plupart des cas d’usage. Facilite la définition des en-têtes, l’ajout de texte brut, l’ajout d’alternatives HTML (add_alternative()) et la mise en pièce jointe de fichiers avec moins de code passe-partout.
- MIMEText : bloc de construction de niveau inférieur pour une partie de texte unique (texte brut ou HTML). Utile lorsque vous souhaitez un contrôle explicite sur une partie unique du corps du message.
- MIMEMultipart : conteneur permettant de combiner plusieurs parties MIME (texte + HTML + pièces jointes). Courant dans les exemples anciens ; vous joignez manuellement des parties MIMEText et des fichiers.
Si vous démarrez de zéro, préférez EmailMessage, à moins que vous n’ayez besoin d’une compatibilité avec d’anciens modèles de construction MIME.
Utilisez des variables d’environnement pour les identifiants dans les applications déployées (CI/CD, conteneurs, serveurs) et getpass() pour les scripts locaux interactifs.
Les variables d’environnement permettent de garder les secrets hors du contrôle de code source et des journaux. Stockez des valeurs telles que les noms d’utilisateur/mots de passe SMTP ou les clés API sous la forme SMTP_USER, SMTP_PASS, MAILGUN_API_KEY, etc., et lisez-les lors de l’exécution.
getpass.getpass() demande un mot de passe de manière sécurisée sans l’afficher dans le terminal : pratique pour les scripts rapides ou les tests locaux.
Un modèle courant consiste à : lire d’abord à partir de l’environnement, puis recourir à getpass() uniquement en cas d’absence.
Yagmail est conçu spécifiquement pour les flux de travail de Gmail, il réduit donc le code passe-partout SMTP et fluidifie les tâches courantes de Gmail.
Principaux avantages lors de l’utilisation de Gmail :
- Moins de code : configuration minimale pour envoyer des messages, du code HTML et des pièces jointes.
- Ergonomie axée sur Gmail : API plus conviviale pour la rédaction de messages et la gestion des pièces jointes.
- Itération plus rapide : idéal pour les scripts et les outils internes où vous souhaitez que la fonction « envoyer un email » soit simple, sans avoir à gérer manuellement les parties MIME.
Si vous envoyez strictement des emails via Gmail et souhaitez moins d’éléments mobiles que la construction brute smtplib + MIME, Yagmail est souvent la voie la plus rapide.
Avec python-emails, vous pouvez généralement :
- Générer le rendu d’un modèle (souvent HTML + texte) à l’aide des aides de création de modèles de la bibliothèque (ou transmettre du contenu pré-rendu depuis votre propre moteur de modèles).
- Joindre les paramètres DKIM à l’aide de la clé privée et du sélecteur DKIM de votre domaine avant l’envoi.
Dans la pratique, vous devrez :
- Créer un objet d’email (objet/de/à)
- Fournir des corps HTML/texte rendus (et éventuellement des variables pour les modèles)
- Configurer la signature DKIM à l’aide des éléments suivants :
- un sélecteur (par exemple, mailgun ou par défaut)
- votre domaine de signature
- la clé privée DKIM (chargée de manière sécurisée depuis les variables d’environnement ou un gestionnaire de secrets)
Pour la production, gardez la clé privée DKIM en dehors du code source (variables d’environnement ou fichiers secrets montés), et validez la signature en vérifiant les en-têtes de message dans une messagerie qui affiche la signature DKIM et les résultats d’authentification.
Comment envoyer plusieurs emails personnalisés ?