Migrationsleitfaden

Von SendGrid zu Mail.Land migrieren

Oft ist die Änderung nur ein SMTP-Host oder ein API-Aufruf. Dieser Leitfaden ordnet die gängigen SendGrid-Felder Mail.Land zu und führt die Unterschiede auf, die eine Codeänderung erfordern.

Kostenlos starten Hilfe bei der Migration anfragen

SMTP

# 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>

SendGrid-Konzepte in Mail.Land

SendGrid-Konzepte in Mail.Land
SendGrid	Mail.Land
API-Schlüssel	API-Schlüssel (Zugangsdaten), beschränkbar auf die API oder SMTP, auf Domains und auf IP-Adressen
Absenderauthentifizierung	Domain-Verifizierung (SPF, DKIM, DMARC und Return-Path)
Dynamische Templates	Templates mit {{name}}-Platzhaltern
Sperrlisten und Abmeldegruppen	Sperrlisten-Einträge mit einem Geltungsbereich: alle E-Mails, nur Marketing oder eine einzelne Mailingliste
Event Webhook	Mit HMAC-SHA256 signierte Webhooks
Inbound Parse	Inbound-Routen

SMTP umstellen: drei Einstellungen ändern

Wenn Sie über SMTP senden, ändern Sie Host, Port und Passwort. Der Benutzername kann apikey bleiben, weil Mail.Land ihn ignoriert und allein mit dem Schlüssel authentifiziert.

SMTP umstellen: drei Einstellungen ändern
Einstellung	SendGrid	Mail.Land
Host	smtp.sendgrid.net	smtp.mail.land
Port	25, 587 oder 2525 (TLS) oder 465 (SSL)	587 mit STARTTLS
Benutzername	apikey	Beliebiger Wert, zum Beispiel apikey
Passwort	Ihr SendGrid-API-Schlüssel	Ein Mail.Land-API-Schlüssel mit aktiviertem SMTP

Mail.Land akzeptiert eine Anmeldung erst nach STARTTLS, und Port 465 wird nicht angeboten. Wenn Ihre Anwendung Port 465 verwendet, stellen Sie sie auf Port 587 mit STARTTLS um.

Dokumentation zum SMTP-Relay

API-Aufruf umstellen

Der Sendeaufruf von Mail.Land verwendet einen flacheren JSON-Body und den Header X-API-Key. Hier ist dieselbe Nachricht in beiden APIs.

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"]
  }'

Feldzuordnung für den Sendeaufruf

Von POST /v3/mail/send zu POST /v1/transactional/send.

Feldzuordnung für den Sendeaufruf
SendGrid	Mail.Land	Hinweis
`Authorization: Bearer <key>`	`X-API-Key: <key>`	Ein anderer Header.
`from.email, from.name`	`from.email, from.name`	Die Adresse muss zu einer verifizierten Domain gehören.
`personalizations[].to[]`	`to[]`	Bis zu 5 Empfänger pro Anfrage mit einem Transaktionsschlüssel. Für den Massenversand verwenden Sie den Batch-Versand mit einem Marketing-Schlüssel.
`personalizations[].cc, bcc`	`Keine Entsprechung`	Nicht unterstützt. Senden Sie jedem Empfänger eine eigene Nachricht.
`personalizations[].dynamic_template_data`	`to[].variables`	Werte pro Empfänger. Verwenden Sie die variables auf oberster Ebene für Werte, die für alle Empfänger gleich sind.
`subject`	`subject`	Erforderlich, sofern Sie kein Template verwenden.
`content[] (text/html)`	`htmlContent`
`content[] (text/plain)`	`textContent`
`template_id`	`templateId`	Legen Sie das Template zuerst in Mail.Land neu an; die ID ändert sich.
`reply_to.email`	`replyTo`	Eine einfache Adresszeichenkette.
`categories, custom_args`	`tags`	Tags erscheinen in den Analysen und in Webhook-Ereignissen.
`headers`	`customHeaders`
`attachments[].content, filename, type`	`attachments[].content, fileName, contentType`	Base64-Inhalt. Bis zu 10 Anhänge und insgesamt 10 MiB.
`attachments[].disposition, content_id`	`attachments[].inline, contentId`	inline: true für ein eingebettetes Bild.
`send_at (Unix-Zeit, bis zu 72 Stunden im Voraus)`	`scheduledAt (Datum und Uhrzeit in UTC, bis zu 7 Tage im Voraus)`
`tracking_settings (open, click)`	`tracking.opens, tracking.clicks`	Für Öffnungen haben die eigenen Tracking-Einstellungen einer Domain Vorrang.
`asm.group_id`	`Keine Entsprechung im Sendeaufruf`	Marketing-Abmeldungen werden über Listen und Kampagnen in Mail.Land abgewickelt. Importieren Sie bestehende Gruppenabmeldungen, siehe unten.
`Keine Entsprechung`	`Header X-Idempotency-Key`	Innerhalb des Aufbewahrungszeitraums gibt eine Wiederholung mit demselben Schlüssel die ursprüngliche Antwort zurück, statt erneut zu senden.

Beide APIs antworten mit 202 Accepted. Der Antworttext von Mail.Land enthält eine jobId, eine Nachrichten-ID pro Empfänger sowie die Listen der angenommenen und abgelehnten Empfänger.

Dokumentation zur REST-API

Importieren Sie zuerst Ihre Sperrlisten

Importieren Sie sie vor Ihrem ersten Versand über Mail.Land, damit Personen, die sich abgemeldet oder beschwert haben, von Anfang an gesperrt bleiben. Exportieren Sie jede Liste aus SendGrid als CSV und importieren Sie sie mit dem passenden Typ und Geltungsbereich, im Dashboard oder mit POST /v1/transactional/suppressions/import.

Importieren Sie zuerst Ihre Sperrlisten
SendGrid-Liste	Mail.Land-Typ	Geltungsbereich
Bounces	`HardBounce`	Global
Spam Reports	`Complaint`	Global
Invalid Emails	`Invalid`	Global
Global Unsubscribes	`Unsubscribe`	Global
Group Unsubscribes	`Unsubscribe`	List, für die passende Mailingliste in Mail.Land; Marketing sperrt alle Marketing-E-Mails

SendGrid-Blocks sind meist vorübergehende Ablehnungen. Prüfen Sie sie vor dem Import, statt sie alle zu sperren.

Dokumentation zu Sperrlisten

Richten Sie Ihre Webhooks auf Mail.Land aus

Fügen Sie Ihren Endpunkt in Mail.Land hinzu, wählen Sie die Ereignisse und prüfen Sie den Header X-MLND-Signature mit dem Geheimnis Ihres Webhooks. Die Ereignisnamen unterscheiden sich von denen bei SendGrid, passen Sie daher Ihren Handler an:

Richten Sie Ihre Webhooks auf Mail.Land aus
SendGrid-Ereignis	Mail.Land-Ereignis
`delivered`	`message.delivered`
`deferred`	`message.deferred`
`bounce`	`message.bounced`
`open, click`	Noch nicht verfügbar
`spamreport`	`message.complained`
`unsubscribe`	`message.unsubscribed`

Deduplizieren Sie anhand des Felds event_id: Eine wiederholte Zustellung trägt dieselbe Ereignis-ID. Für die Ereignisse open und click von SendGrid gibt es heute keinen entsprechenden Mail.Land-Webhook: Öffnungs- und Klick-Ereignisse sind im Katalog aufgeführt, werden aber nicht gesendet.

Prüfung von Webhook-Signaturen

Schritt für Schritt umstellen

Fügen Sie Ihre Absender-Domain in Mail.Land hinzu und verifizieren Sie sie. Behalten Sie Ihre SendGrid-Einträge: Ergänzen Sie Ihren bestehenden SPF-Eintrag um include:spf.mlnd.net, statt einen zweiten anzulegen, und behalten Sie einen einzigen DMARC-Eintrag.
Importieren Sie Ihre Sperrlisten.
Erstellen Sie einen auf reine Protokollierung eingestellten Sandbox-Schlüssel und führen Sie Ihre Integrationstests gegen Mail.Land aus, ohne E-Mails zuzustellen.
Senden Sie echte Nachrichten an Adressen, die Sie selbst kontrollieren, und prüfen Sie sie im E-Mail-Protokoll.
Verlagern Sie eine Anwendung oder einen kleinen Teil des Traffics und beobachten Sie dann Zustellung, Bounces und Beschwerden.
Solange beide Anbieter laufen, übertragen Sie neue Abmeldungen, Beschwerden und Bounces von SendGrid zu Mail.Land und führen vor der Umstellung des letzten Traffics einen abschließenden Abgleich durch.
Verlagern Sie den Rest und lassen Sie SendGrid aktiv, bis die letzten geplanten und erneut versuchten Nachrichten versendet sind.

Häufig gestellte Fragen

Kann ich während der Tests weiter über SendGrid senden?

Ja. Die Verifizierung einer Domain in Mail.Land hindert SendGrid nicht daran, für diese Domain zu senden. Sie können also beide parallel betreiben und den Traffic schrittweise verlagern.

Unterstützt Mail.Land cc und bcc?

Nicht im Sendeaufruf. Senden Sie stattdessen jedem Empfänger eine eigene Nachricht.

Gibt es ein offizielles SDK für Mail.Land?

Noch nicht. Die Dokumentation enthält Beispiele zum Kopieren für die REST-API in acht Sprachen, und jede SMTP-Bibliothek funktioniert mit dem Relay.

Was geschieht mit meinen Abmeldegruppen?

Importieren Sie die Abmeldungen jeder Gruppe mit dem Geltungsbereich List für die passende Mailingliste in Mail.Land und senden Sie an diese Liste, damit die Präferenz greift. Der Geltungsbereich Marketing ist die umfassendere Ausweichlösung: Er sperrt alle Marketing-E-Mails an diese Adresse.

Bereit für den Wechsel von SendGrid?

Erstellen Sie ein kostenloses Konto und senden Sie noch heute Ihren ersten Test. Wenn Sie Hilfe möchten, beschreiben Sie uns Ihre Einrichtung.

Kostenlos starten Hilfe bei der Migration anfragen