Guide
Choisir entre l’API et SMTP
Comparez l’API REST d’Emailit et le relais SMTP fonctionnalité par fonctionnalité, des modèles et de la programmation à l’idempotence et aux webhooks, et choisissez la bonne option.
Emailit accepte les e-mails transactionnels de deux façons : l’API REST et le relais SMTP. Ce guide les compare pour vous aider à choisir l’un des deux, ou à utiliser les deux dans le même espace de travail.
En bref
- Utilisez l’API pour du nouveau code. Elle en fait plus : modèles, programmation, relances idempotentes, métadonnées, réglages de suivi par e-mail et réponse JSON avec un ID pour chaque destinataire.
- Utilisez SMTP quand le logiciel que vous utilisez dispose déjà de paramètres SMTP, comme un CMS, le mailer d’un framework, un outil de support, un appareil ou une ancienne application. Vous modifiez quatre paramètres et c’est terminé.
Les deux utilisent les mêmes clés API, domaines vérifiés, liste d’adresses bloquées, limites d’envoi, logs et webhooks. Vous pouvez changer plus tard sans toucher au DNS.
Comparatif des fonctionnalités
| Fonctionnalité | API REST | Relais SMTP |
|---|---|---|
| Endpoint | POST https://api.emailit.com/v2/emails |
smtp.emailit.com, ports 587, 465, 2525, 2587 et 25 |
| Authentification | Authorization: Bearer secret_… |
AUTH PLAIN ou LOGIN, nom d’utilisateur emailit, mot de passe = clé API |
| Contenu | html, text ou un modèle enregistré |
Un message MIME complet, envoyé tel quel |
| Modèles et variables | template (ID ou alias) plus variables, rendu avec Temple |
Non disponible. Effectuez le rendu du message avant de l’envoyer. |
| Programmation | scheduled_at au format ISO 8601, en horodatage Unix ou en anglais courant comme tomorrow at 9am |
Non disponible. L’e-mail est mis en file d’attente immédiatement. |
| Pièces jointes | content en Base64 ou une url qu’Emailit télécharge (jusqu’à 25 Mo chacune). content_id rend une image intégrée. |
Parties MIME standard |
| Taille du message | 40 Mo | 40 Mo |
| Destinataires par message | Jusqu’à 50 dans chacun des champs to, cc et bcc |
Pas de limite fixe par transaction |
| Idempotence | En-tête Idempotency-Key, rejoué pendant 24 heures |
Non disponible. Une transaction relancée peut envoyer deux fois. |
| Métadonnées | Objet meta, renvoyé dans les payloads de webhook |
Non disponible |
| En-têtes personnalisés | Objet headers |
N’importe quel en-tête du message |
| Suivi des ouvertures et des clics | Par e-mail avec tracking, ou la valeur par défaut du domaine |
La valeur par défaut du domaine uniquement |
Webhooks email.accepted et email.scheduled |
Oui | Non. Les événements ultérieurs comme email.delivered et email.bounced fonctionnent de la même façon. |
| ID des e-mails | La réponse contient id, et ids avec un ID par destinataire |
Réponse finale 250 2.0.0 OK: queued as em_… |
| Erreurs | Codes de statut HTTP avec un corps JSON | Codes de réponse SMTP, par exemple 535 ou 550 |
| Limites d’envoi | Partagées par espace de travail. 429 avec les en-têtes ratelimit-* et retry-after. |
Partagées par espace de travail. Réponses 452. |
| Crédits | 1 par destinataire | 1 par destinataire |
| Log de requêtes | Email APILogs, source API | Email APILogs, source SMTP |
Une fois l’e-mail accepté, les deux canaux se comportent de la même façon. Chaque destinataire obtient un e-mail avec un ID em_, qui apparaît dans Email APIEmails et peut être annulé, relancé ou transféré depuis le tableau de bord ou via l’API.
Quand utiliser l’API
Choisissez l’API quand vous écrivez vous-même le code d’envoi, surtout si vous avez besoin de l’un de ces éléments :
- Modèles. Les designers modifient un modèle dans le tableau de bord et votre code l’envoie par son alias avec
variables. Consultez Modèles. - Relances sûres. Envoyez une
Idempotency-Keyavec chaque requête et relancez en cas d’erreur réseau sans envoyer deux fois. Consultez Idempotence. - Programmation. Envoyez un rappel pour le lendemain matin sans votre propre file de tâches, et reprogrammez-le ou annulez-le jusqu’à 3 minutes avant son envoi. Consultez Programmation.
- Corrélation. Joignez vos propres ID dans
metaet rapprochez les événements webhook de vos enregistrements. Consultez En-têtes et métadonnées. - Erreurs claires. Un
422pour un domaine non vérifié ou un402pour des crédits insuffisants est plus facile à gérer qu’une chaîne de réponse SMTP.
Quand utiliser SMTP
Choisissez SMTP quand vous ne pouvez pas ou ne voulez pas modifier de code :
- Les logiciels du commerce comme WordPress, un outil de support ou un outil de supervision disposant d’une page de paramètres SMTP.
- Les mailers de frameworks qui fonctionnent déjà via SMTP, comme Laravel, Rails, Django ou Nodemailer. Vous pourrez passer à l’API plus tard.
- Les migrations rapides depuis un autre fournisseur. Remplacez l’hôte, le port, le nom d’utilisateur et le mot de passe, puis testez.
- Les appareils et les scripts qui ne parlent que SMTP, comme les imprimantes, les scanners ou les tâches cron.
À savoir avant de vous appuyer sur SMTP :
- Emailit ne lit pas les en-têtes propres aux autres fournisseurs via SMTP. Le suivi dépend des paramètres Track loads et Track clicks du domaine d’envoi.
- Emailit remplace votre en-tête
Message-IDpar le sien et supprime l’en-têteReply-Tolorsqu’il est identique àFrom. - Utilisez toujours TLS. Le port 587 avec STARTTLS est recommandé, et le 465 utilise TLS dès le premier octet. Consultez Paramètres SMTP.
Utiliser les deux
De nombreuses équipes utilisent les deux : l’API pour les e-mails de l’application et SMTP pour un CMS ou des outils internes. Utilisez une clé API distincte pour chacun afin de les distinguer dans les logs et de pouvoir régénérer l’une sans casser l’autre. Une clé Sending Only limitée à un domaine convient bien comme identifiants SMTP stockés dans un logiciel tiers. Consultez Clés API.