Quitter Mailgun
Gardez le SDK Mailgun et envoyez par OpenEmail. Changez son URL de base et sa clé, et votre code d’envoi reste tel quel.
Ce qu’il faut changer
Pointez le SDK vers https://api.openemail.uk/compat/mailgun et donnez-lui, à la place de la clé Mailgun, une clé d’API OpenEmail dotée de la permission emails:send. Elle sert de mot de passe à la même authentification HTTP Basic, et le nom d’utilisateur n’est pas vérifié. Le domaine du chemin doit être l’un des domaines de l’espace de travail, et l’adresse From décide si un message peut partir, comme partout dans OpenEmail.
import formData from 'form-data'import Mailgun from 'mailgun.js' const mailgun = new Mailgun(formData)const mg = mailgun.client({ username: 'api', key: process.env.OPENEMAIL_API_KEY, url: 'https://api.openemail.uk/compat/mailgun',}) await mg.messages.create('acme.com', { from: 'Acme Billing <[email protected]>', to: ['[email protected]'], subject: 'Your invoice', html: '<p>Your invoice is attached.</p>',})En Ruby, le second argument est l’hôte et le chemin, sans schéma. En PHP, le SDK ne garde que l’hôte du point de terminaison qu’on lui donne : le chemin passe donc par AddPathPlugin, de php-http, que le SDK installe déjà. Le paquet Python officiel peut journaliser un avertissement indiquant que l’hôte n’est pas celui de Mailgun, et envoie quand même. Il relance aussi une requête qui a échoué avec 429 ou un 5xx, c’est pourquoi OpenEmail répond 400 plutôt que 5xx dès qu’une partie d’un lot est partie.
Ce qui correspond à quoi
Le point d’accès servi est POST /v3/{domain}/messages, en multipart/form-data, nécessaire pour les pièces jointes, ou en application/x-www-form-urlencoded. Un nom de champ qui se termine par [] est lu sans cette fin.
| Mailgun | Dans OpenEmail |
|---|---|
| from | L’expéditeur, avec son nom. |
| to | Des destinataires, répétés ou séparés par des virgules. Avec cc et bcc, jusqu’à 50 par message. |
| subject | L’objet. |
| html | Le corps HTML. text devient le corps texte, et l’un des deux, ou template, est obligatoire. |
| attachment | Des fichiers, 20 au plus et 5 Mo en tout. |
| inline | Une image que le HTML utilise comme cid: avec son nom de fichier est insérée là où elle apparaît. Tout autre fichier intégré arrive comme une pièce jointe ordinaire. |
| o:tag | Des tags nommés tag, tag_2 et ainsi de suite, chacun portant un tag. |
| v: | Chaque variable devient un tag avec son nom et sa valeur. Avec o:tag, au plus 10 par message. |
| o:deliverytime | Un envoi programmé, jusqu’à un an à l’avance. Une heure déjà passée envoie tout de suite. |
| o:tracking | Avec o:tracking-clicks et o:tracking-opens, active ou désactive le suivi pour le message. htmlonly compte comme activé. |
| o:testmode | yes enregistre le message comme envoyé sans le distribuer, comme le fait une clé oe_test_. |
| h:Reply-To | L’adresse de réponse. Tout autre champ h: devient un en-tête personnalisé : X-*, List-*, Precedence, Auto-Submitted, Importance, Priority et Feedback-ID. |
| recipient-variables | Un envoi par lot. Chaque adresse de to reçoit son propre message, où %recipient.key% est rempli à partir de ses variables et %recipient% par son adresse, et cc et bcc figurent sur chacun. Un espace réservé sans valeur reste tel quel. |
| template | Le slug ou l’id (tpl_...) d’un modèle OpenEmail, rempli à partir de t:variables, ou à défaut de h:X-Mailgun-Variables. t:version choisit une version par son numéro. |
Ce qui est refusé, et pourquoi
- Un
templateavechtmloutext, car un modèle OpenEmail fournit le corps entier, et unt:versionqui n’est pas un numéro de version. o:deliverytime-optimize-periodeto:time-zone-localize, car OpenEmail ne choisit pas d’heure d’envoi par destinataire. Les autres en-têtesh:X-Mailgun-, qui sont des instructions pour Mailgun : utilisez plutôt l’optiono:correspondante.amp-htmlseul. À côté dehtmlou detext, il est laissé de côté, car ceux-ci portent déjà le message.- Plus d’une adresse de réponse, plus de 10 tags, un nom de tag fait d’autre chose que de lettres, de chiffres, de
_et de-, et un lot de plus de 100 destinataires. Mailgun en accepte 1 000 : découpez donc les lots plus grands.
o:dkim, o:require-tls, o:skip-verification, o:sending-ip, o:sending-ip-pool, o:tracking-pixel-location-top, o:archive-to, o:deliver-within et t:text sont acceptés et ne changent rien.
Réponses et erreurs
- Un envoi répond 200 avec le message
Queued. Thank you.et unid: l’id du message OpenEmail entre chevrons, queGET /emails/{id}et les webhooks utilisent sans eux. Un envoi par lot crée un message par destinataire, chacun avec son propre id, et répond avec le premier. Un en-têteIdempotency-Keyfonctionne comme dans le reste de l’API. - Une clé absente ou inconnue répond 401 avec le texte brut
Forbidden, et un domaine que l’espace de travail ne possède pas répond 404 avecDomain not found. Tout le reste revient sous la forme d’unmessage: 400 pour un message qui ne peut pas être envoyé, 403 pour une clé sansemails:send, une adresse From que la clé ne peut pas utiliser, un domaine qui ne peut pas encore envoyer ou un espace de travail qui a épuisé son quota d’envoi, et 413 pour un corps de plus de 25 Mo ou des pièces jointes de plus de 5 Mo. - Quand un destinataire d’un lot échoue alors que d’autres ont été acceptés, l’erreur nomme les messages déjà envoyés et répond 400, pour qu’un SDK qui relance ne les envoie pas deux fois.