Quitter SendGrid
Gardez le SDK SendGrid 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/sendgrid et donnez-lui, à la place de la clé SendGrid, une clé d’API OpenEmail dotée de la permission emails:send. Elle passe dans le même en-tête Authorization: Bearer. Vos appels qui envoient du courrier restent tels quels, et l’adresse From décide si un message peut partir, comme partout dans OpenEmail.
import sgMail from '@sendgrid/mail'import client from '@sendgrid/client' client.setApiKey(process.env.OPENEMAIL_API_KEY)client.setDefaultRequest('baseUrl', 'https://api.openemail.uk/compat/sendgrid')sgMail.setClient(client) await sgMail.send({ from: '[email protected]', to: '[email protected]', subject: 'Your invoice', html: '<p>Your invoice is attached.</p>',})En Node, définissez d’abord la clé sur le client, puis l’URL de base, puis confiez le client au paquet mail. N’appelez plus sgMail.setApiKey ensuite, car cela remet l’URL de base sur SendGrid. Le SDK avertit que la clé ne commence pas par SG., ce qui est sans conséquence. En Python, en Ruby et en PHP, indiquez l’hôte sans barre oblique finale.
Ce qui correspond à quoi
Le point d’accès servi est POST /v3/mail/send. Chaque entrée de personalizations devient un message OpenEmail distinct avec son propre id, si bien qu’une requête envoie au plus 100 messages.
| SendGrid | Dans OpenEmail |
|---|---|
| from | L’expéditeur, avec son nom. Une personnalisation peut indiquer son propre from. |
| personalizations | Un message chacune. Ses to, cc et bcc comptent jusqu’à 50 destinataires à eux trois, et ses subject, headers, custom_args, send_at et substitutions ne valent que pour ce message. |
| subject | L’objet, sauf si une personnalisation fixe le sien. |
| content | text/plain devient le corps texte et text/html le corps HTML. text/x-amp-html est laissé de côté, car le corps HTML porte déjà le message. |
| attachments | Des fichiers, 20 au plus et 5 Mo en tout. Une image intégrée dont le HTML utilise le content_id comme cid: est insérée là où elle apparaît. Tout autre fichier intégré arrive comme une pièce jointe ordinaire. |
| reply_to | L’adresse de réponse. reply_to_list fonctionne aussi tant qu’elle ne contient qu’une adresse. |
| headers | Des en-têtes personnalisés : X-*, List-*, Reply-To, Precedence, Auto-Submitted, Importance, Priority et Feedback-ID. Une personnalisation ajoute les siens. |
| categories | Des tags nommés category, category_2 et ainsi de suite, chacun portant une catégorie. |
| custom_args | Des tags de mêmes noms et valeurs. Les valeurs d’une personnalisation l’emportent. |
| send_at | Un envoi programmé, jusqu’à un an à l’avance. Une heure déjà passée envoie tout de suite. |
| substitutions | Chaque clé est remplacée par sa valeur dans l’objet, le corps texte et le corps HTML de ce message. |
| template_id | L’id (tpl_...) ou le slug d’un modèle OpenEmail, rempli à partir de dynamic_template_data. |
| tracking_settings | open_tracking.enable et click_tracking.enable activent ou désactivent le suivi des ouvertures et des clics pour le message. |
| mail_settings | sandbox_mode.enable vérifie la requête, l’expéditeur et le modèle, puis répond 200 sans rien envoyer. |
Un message porte au plus 10 tags, catégories et custom_args confondus. Une requête qui en demande davantage est refusée plutôt que tronquée, pour que rien de ce que vous avez envoyé ne disparaisse sans un mot.
Ce qui est refusé, et pourquoi
- Un id de modèle SendGrid dans
template_id, commed-…. Les modèles restent chez SendGrid : recréez donc le modèle dans OpenEmail et envoyez son id ou son slug. contentà côté detemplate_id, car un modèle OpenEmail fournit le corps entier.substitutionsavec un modèle pour la même raison : passez les valeurs dansdynamic_template_data.- Plus d’une adresse de réponse,
reply_toetreply_to_listensemble, et les types de contenu autres que le texte et le HTML. Envoyez une invitation d’agenda en pièce jointe.ics. mail_settings.footeractivé, ainsi quesections, car OpenEmail n’écrit pas de texte dans votre message.- Plus de 10 tags, un nom de tag fait d’autre chose que de lettres, de chiffres, de
_et de-, un en-tête hors de la liste ci-dessus, et plus de 100 personnalisations dans une requête.
asm, batch_id, ip_pool_name, les réglages de contournement de mail_settings, subscription_tracking, ganalytics, click_tracking.enable_text et open_tracking.substitution_tag sont acceptés et ne changent rien. Les adresses de la liste de suppression de l’espace de travail sont toujours ignorées, quoi qu’en dise un réglage de contournement.
Réponses et erreurs
- Un envoi répond 202 avec un corps vide et l’id du message OpenEmail dans
X-Message-Id, celui qu’utilisentGET /emails/{id}et les webhooks. Avec plusieurs personnalisations, il contient l’id du premier message. Un en-têteIdempotency-Keyfonctionne comme dans le reste de l’API. - Les erreurs reviennent sous la forme
errors, une liste demessage,fieldethelp: 400 pour une requête qui ne peut pas être envoyée, 401 pour une clé absente ou inconnue, 403 pour une clé sansemails:sendou une adresse From que la clé ne peut pas utiliser ou dont le domaine ne peut pas encore envoyer, 413 pour un corps de plus de 30 Mo ou des pièces jointes de plus de 5 Mo, et 429 quand l’espace de travail a épuisé son quota d’envoi. - Quand une personnalisation échoue alors que des précédentes ont été acceptées, l’erreur nomme les messages déjà envoyés, pour qu’une nouvelle tentative puisse les laisser de côté.