Guide de migration
Migrer de SendGrid vers Mail.Land
Souvent, le changement se limite à un hôte SMTP ou à un appel API. Ce guide fait correspondre les champs SendGrid courants à Mail.Land et liste les différences qui nécessitent une modification du code.
# Before (SendGrid)
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=<your SendGrid API key>
# After (Mail.Land)
SMTP_HOST=smtp.mail.land
SMTP_PORT=587 # STARTTLS
SMTP_USER=apikey # any value; Mail.Land ignores it
SMTP_PASS=<your Mail.Land API key with SMTP enabled>Les concepts SendGrid dans Mail.Land
| SendGrid | Mail.Land |
|---|---|
| Clé API (API key) | Clé API (identifiant), limitée à l’API ou au SMTP, à des domaines et à des adresses IP |
| Authentification de l’expéditeur (Sender authentication) | Vérification du domaine (SPF, DKIM, DMARC et return path) |
| Modèles dynamiques (Dynamic templates) | Modèles avec des variables {{name}} |
| Suppressions et groupes de désabonnement (unsubscribe groups) | Suppressions avec une portée : tous les e-mails, marketing uniquement ou une liste de diffusion donnée |
| Event Webhook | Webhooks signés avec HMAC-SHA256 |
| Inbound Parse | Routes entrantes |
Basculer le SMTP : modifiez trois paramètres
Si vous envoyez via SMTP, modifiez l’hôte, le port et le mot de passe. Le nom d’utilisateur peut rester apikey, car Mail.Land l’ignore et authentifie uniquement avec la clé.
| Paramètre | SendGrid | Mail.Land |
|---|---|---|
| Hôte | smtp.sendgrid.net | smtp.mail.land |
| Port | 25, 587 ou 2525 (TLS), ou 465 (SSL) | 587 avec STARTTLS |
| Nom d’utilisateur | apikey | N’importe quelle valeur, par exemple apikey |
| Mot de passe | Votre clé API SendGrid | Une clé API Mail.Land avec SMTP activé |
Mail.Land n’accepte l’authentification qu’après STARTTLS, et le port 465 n’est pas proposé. Si votre application utilise le port 465, passez au port 587 avec STARTTLS.
Modifier l’appel API
L’appel d’envoi de Mail.Land utilise un corps JSON plus plat et l’en-tête X-API-Key. Voici le même message dans les deux API.
curl -X POST https://api.sendgrid.com/v3/mail/send \
-H "Authorization: Bearer $SENDGRID_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"personalizations": [{
"to": [{ "email": "[email protected]", "name": "Jane" }],
"dynamic_template_data": { "orderNumber": "12345" }
}],
"from": { "email": "[email protected]", "name": "Your Shop" },
"reply_to": { "email": "[email protected]" },
"subject": "Order 12345 has shipped",
"content": [
{ "type": "text/plain", "value": "Your order is on its way." },
{ "type": "text/html", "value": "<p>Your order is on its way.</p>" }
],
"categories": ["order-shipped"]
}'curl -X POST https://api.mail.land/v1/transactional/send \
-H "X-API-Key: $MAILLAND_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": [{
"email": "[email protected]", "name": "Jane",
"variables": { "orderNumber": "12345" }
}],
"from": { "email": "[email protected]", "name": "Your Shop" },
"replyTo": "[email protected]",
"subject": "Order 12345 has shipped",
"textContent": "Your order is on its way.",
"htmlContent": "<p>Your order is on its way.</p>",
"tags": ["order-shipped"]
}'Correspondance des champs de l’appel d’envoi
De POST /v3/mail/send à POST /v1/transactional/send.
| SendGrid | Mail.Land | Remarque |
|---|---|---|
Authorization: Bearer <key> | X-API-Key: <key> | Un en-tête différent. |
from.email, from.name | from.email, from.name | L’adresse doit appartenir à un domaine vérifié. |
personalizations[].to[] | to[] | Jusqu’à 5 destinataires par requête avec une clé transactionnelle. Pour les envois en masse, utilisez l’envoi par lots avec une clé marketing. |
personalizations[].cc, bcc | Aucun | Non pris en charge. Envoyez un message distinct à chaque destinataire. |
personalizations[].dynamic_template_data | to[].variables | Valeurs propres à chaque destinataire. Utilisez les variables de premier niveau pour les valeurs communes à tous les destinataires. |
subject | subject | Obligatoire, sauf si vous utilisez un modèle. |
content[] (text/html) | htmlContent | |
content[] (text/plain) | textContent | |
template_id | templateId | Recréez d’abord le modèle dans Mail.Land ; l’identifiant change. |
reply_to.email | replyTo | Une simple chaîne contenant l’adresse. |
categories, custom_args | tags | Les tags apparaissent dans les statistiques et dans les événements de webhook. |
headers | customHeaders | |
attachments[].content, filename, type | attachments[].content, fileName, contentType | Contenu encodé en Base64. Jusqu’à 10 pièces jointes et 10 Mio au total. |
attachments[].disposition, content_id | attachments[].inline, contentId | inline: true pour une image intégrée. |
send_at (horodatage Unix, jusqu’à 72 heures à l’avance) | scheduledAt (date et heure UTC, jusqu’à 7 jours à l’avance) | |
tracking_settings (open, click) | tracking.opens, tracking.clicks | Pour les ouvertures, les paramètres de suivi propres au domaine prévalent. |
asm.group_id | Aucun dans l’appel d’envoi | Les désabonnements marketing sont gérés par les listes et les campagnes de Mail.Land. Importez les désabonnements de groupe existants (voir ci-dessous). |
Aucun équivalent | En-tête X-Idempotency-Key | Pendant la période de conservation, une nouvelle tentative avec la même clé renvoie la réponse d’origine au lieu d’envoyer à nouveau. |
Les deux API répondent 202 Accepted. Le corps de la réponse de Mail.Land comprend un jobId, un identifiant de message par destinataire, ainsi que les listes des destinataires acceptés et refusés.
Importez d’abord vos listes de suppression
Importez-les avant votre premier envoi via Mail.Land, afin que les personnes qui se sont désabonnées ou ont déposé une plainte restent exclues des envois dès le départ. Exportez chaque liste depuis SendGrid au format CSV, puis importez-la avec le type et la portée correspondants, dans le tableau de bord ou avec POST /v1/transactional/suppressions/import.
| Liste SendGrid | Type Mail.Land | Portée |
|---|---|---|
| Rebonds (Bounces) | HardBounce | Global |
| Signalements de spam (Spam reports) | Complaint | Global |
| Adresses non valides (Invalid emails) | Invalid | Global |
| Désabonnements globaux (Global unsubscribes) | Unsubscribe | Global |
| Désabonnements de groupe (Group unsubscribes) | Unsubscribe | List, pour la liste de diffusion Mail.Land correspondante ; Marketing bloque tous les e-mails marketing |
Les blocages (blocks) SendGrid sont généralement des refus temporaires. Examinez-les avant de les importer plutôt que de tous les supprimer.
Redirigez vos webhooks vers Mail.Land
Ajoutez votre endpoint dans Mail.Land, choisissez les événements et vérifiez l’en-tête X-MLND-Signature avec le secret de votre webhook. Les noms d’événements diffèrent de ceux de SendGrid ; mettez donc à jour votre gestionnaire :
| Événement SendGrid | Événement Mail.Land |
|---|---|
delivered | message.delivered |
deferred | message.deferred |
bounce | message.bounced |
open, click | Pas encore disponible |
spamreport | message.complained |
unsubscribe | message.unsubscribed |
Dédoublonnez à partir du champ event_id : une livraison relancée porte le même identifiant d’événement. Les événements open et click de SendGrid n’ont pas aujourd’hui de webhook équivalent chez Mail.Land : les événements d’ouverture et de clic figurent au catalogue mais ne sont pas envoyés.
Basculez étape par étape
- Ajoutez et vérifiez votre domaine d’envoi dans Mail.Land. Conservez vos enregistrements SendGrid : ajoutez include:spf.mlnd.net à votre enregistrement SPF existant au lieu d’en créer un second, et conservez un seul enregistrement DMARC.
- Importez vos listes de suppression.
- Créez une clé sandbox configurée en mode journalisation seule, et exécutez vos tests d’intégration sur Mail.Land sans livrer d’e-mails.
- Envoyez de vrais messages à des adresses que vous contrôlez et vérifiez-les dans le journal des e-mails.
- Transférez une application ou une petite partie du trafic, puis surveillez la livraison, les rebonds et les plaintes.
- Tant que les deux fournisseurs fonctionnent, copiez vers Mail.Land les nouveaux désabonnements, plaintes et rebonds de SendGrid, et effectuez une synchronisation finale avant de basculer le reste du trafic.
- Transférez le reste et gardez SendGrid actif jusqu’à ce que ses derniers messages programmés et relancés soient partis.
Questions fréquentes
Puis-je continuer à envoyer via SendGrid pendant mes tests ?
Oui. La vérification d’un domaine dans Mail.Land n’empêche pas SendGrid de continuer à envoyer pour ce domaine : vous pouvez utiliser les deux et transférer le trafic progressivement.
Mail.Land prend-il en charge cc et bcc ?
Pas dans l’appel d’envoi. Envoyez plutôt un message distinct à chaque destinataire.
Existe-t-il un SDK officiel Mail.Land ?
Pas encore. La documentation propose des exemples prêts à copier pour l’API REST dans huit langages, et toute bibliothèque SMTP fonctionne avec le relais.
Que deviennent mes groupes de désabonnement ?
Importez les désabonnements de chaque groupe avec la portée List pour la liste de diffusion Mail.Land correspondante, et envoyez à cette liste afin que la préférence s’applique. La portée Marketing est la solution de repli plus large : elle bloque tous les e-mails marketing vers cette adresse.
Prêt à quitter SendGrid ?
Créez un compte gratuit et envoyez votre premier test dès aujourd’hui. Si vous souhaitez de l’aide, décrivez-nous votre configuration.