# 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](/fr/docs/templates/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 API → Logs**, source API | **Email API → Logs**, 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 API → Emails** 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](/fr/docs/templates/).
- **Relances sûres.** Envoyez une `Idempotency-Key` avec chaque requête et relancez en cas d’erreur réseau sans envoyer deux fois. Consultez [Idempotence](/fr/docs/email-api/idempotency/).
- **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](/fr/docs/email-api/scheduling/).
- **Corrélation.** Joignez vos propres ID dans `meta` et rapprochez les événements webhook de vos enregistrements. Consultez [En-têtes et métadonnées](/fr/docs/email-api/headers-and-metadata/).
- **Erreurs claires.** Un `422` pour un domaine non vérifié ou un `402` pour 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-ID` par le sien et supprime l’en-tête `Reply-To` lorsqu’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](/fr/docs/smtp/settings/).

## 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](/fr/docs/developers/api-keys/).

## Étapes suivantes

  - [Démarrage rapide API](/fr/docs/quickstart/api/): Envoyez votre premier e-mail avec cURL ou un SDK.
  - [Démarrage rapide SMTP](/fr/docs/quickstart/smtp/): Testez le relais avec swaks, OpenSSL ou Python.
  - [Envoyer un e-mail](/fr/docs/email-api/send-email/): Toutes les options de l’endpoint d’envoi.
  - [Paramètres SMTP](/fr/docs/smtp/settings/): Hôtes, ports, TLS et codes de réponse.

---
Source: https://emailit.com/fr/docs/get-started/api-or-smtp/