Transaktions-E-Mail-API
Ein REST-Aufruf für jede E-Mail, die Ihr Produkt versendet
Senden Sie Belege, Passwort-Resets, Benachrichtigungen und Kontohinweise über POST /v1/transactional/send. MailLand prüft die Anfrage, signiert jede Nachricht mit dem DKIM-Schlüssel Ihrer Domain, übergibt sie an seine Mailserver und meldet, was mit ihr geschehen ist. Die Server laufen bei Hetzner in Deutschland.
curl -X POST https://api.mail.land/v1/transactional/send \
-H "X-API-Key: ml_pet_..." \
-H "X-Idempotency-Key: order-1042-receipt" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "[email protected]", "name": "Your App" },
"to": [{ "email": "[email protected]", "name": "Jane" }],
"subject": "Your receipt for order 1042",
"htmlContent": "<p>Thanks, Jane. Your payment was received.</p>",
"textContent": "Thanks, Jane. Your payment was received.",
"tags": ["receipt"]
}'Was nach Ihrem API-Aufruf passiert
Vier Stufen, jede für Sie sichtbar: in der Antwort, im Nachrichtenprotokoll oder über einen Webhook.
Geprüft
Die API prüft die Absender-Domain, Berechtigungsumfang und Limits Ihres Schlüssels sowie jeden Empfänger. Gesperrte Adressen werden abgelehnt und in rejectedRecipients aufgeführt; ist der Schutz vor Tippfehlern und Wegwerf-Domains aktiviert, werden auch diese Adressen aufgeführt, bei einem Tippfehler mit einem Korrekturvorschlag.
Eingereiht
Jede angenommene Nachricht wird in die Datenbank von MailLand geschrieben, bevor die API mit 202 Accepted antwortet, und dann an die Zustellwarteschlange übergeben. Die Antwort enthält die Job-ID, eine Nachrichten-ID pro Empfänger und den Zeitpunkt der Einreihung; ein geplanter Versand liefert stattdessen eine Planungs-ID.
Signiert und versendet
Jeder Empfänger erhält eine eigene Kopie mit eigener Nachrichten-ID und ohne sichtbares Cc, signiert mit dem DKIM-Schlüssel Ihrer Domain und versendet über die gemeinsam genutzten Versand-IP-Adressen von MailLand.
Gemeldet
Ereignisse für zugestellt, verzögert, Bounce, fehlgeschlagen und Beschwerde erreichen Ihren Webhook und das Nachrichtenprotokoll. Jedes Ereignis trägt eine Statusversion, sodass Sie die Ereignisse in der richtigen Reihenfolge anwenden können.
Was die API Ihnen bietet
Jede dieser Funktionen ist ein Feld, ein Header oder ein Endpunkt und mit Beispielen dokumentiert.
Gespeicherte Vorlagen mit Variablen
Speichern Sie HTML- und Textvorlagen in MailLand und füllen Sie {{placeholders}} pro Empfänger. Fehlt der Wert einer Variablen, wird die Nachricht nicht mit dem rohen Platzhalter versendet: Die API antwortet mit 422 und nennt, was fehlt.
Idempotenzschlüssel
Senden Sie mit einem Versand einen X-Idempotency-Key-Header. Ein erneuter Versuch mit demselben Schlüssel innerhalb von 24 Stunden liefert die ursprüngliche Antwort und versendet nichts. So entsteht bei einem erneuten Versuch nach einem Netzwerk-Timeout keine zweite Kopie.
Geplanter Versand
Mit scheduledAt planen Sie den Versand bis zu 7 Tage im Voraus. Geplante Nachrichten können Sie über die API auflisten, neu planen oder stornieren, solange sie noch nicht versendet sind.
Anhänge und eingebettete Bilder
Hängen Sie bis zu 10 Dateien und 10 MiB pro Nachricht an, einschließlich eingebetteter Bilder, auf die Ihr HTML per Content-ID verweist.
Tags und eigene Header
Versehen Sie Nachrichten mit Tags, um sie in Analysen, Protokollen und Webhooks zu filtern, fügen Sie eigene Header hinzu und legen Sie pro Nachricht eine Antwortadresse fest.
Vorabprüfung
GET /v1/transactional/send/check zeigt Ihnen, ob Ihr Konto gerade senden kann, mit der aktuellen Auslastung des Ratenlimits und dem Monatskontingent. Einen bestimmten Absender oder Empfänger prüft der Endpunkt nicht.
Sandbox-Schlüssel
Ein Sandbox-Schlüssel nimmt Anfragen an und protokolliert sie, ohne sie zuzustellen, oder stellt nur an eine von Ihnen verwaltete Freigabeliste zu. So erreichen Test-E-Mails nur die Adressen, die Sie auswählen.
Schlüssel mit eingeschränktem Umfang
Beschränken Sie jeden Schlüssel auf einen Stream, auf ausgewählte Absender-Domains, auf eine IP-Freigabeliste, auf Limits pro Minute, Stunde und Tag sowie auf ein Ablaufdatum. Rotieren Sie ihn im Panel oder über die API.
Wissen, was mit jeder Nachricht geschehen ist
Eine Anfrage anzunehmen ist nur die halbe Arbeit. MailLand teilt Ihnen mit, was danach geschah.
Signierte Webhooks
Abonnieren Sie die Ereignisse zugestellt, verzögert, Bounce, fehlgeschlagen und Beschwerde. Jede Anfrage ist mit HMAC-SHA256 im Header X-MLND-Signature signiert und wird wiederholt, wenn Ihr Endpunkt einen Fehler liefert.
Nachrichtenprotokoll
Rufen Sie jede Nachricht über ihre ID auf und sehen Sie jedes Ereignis in ihrem Verlauf. Protokolle werden je nach Tarif 30, 90 oder 180 Tage aufbewahrt.
Automatische Sperrung
Hard Bounces und Beschwerden landen automatisch auf Ihrer Sperrliste, und spätere Sendungen an diese Adressen werden abgelehnt, bevor sie hinausgehen.
Eine v1, die nur wächst
Version 1 der API wird nur erweitert: Neue Felder und Ereignisse können hinzukommen, aber nichts wird entfernt und nichts ändert seine Bedeutung. Eine inkompatible Änderung erscheint als /v2, mindestens 180 Tage im Voraus angekündigt, und /v1 läuft danach noch 180 Tage parallel weiter.
Einfaches HTTPS, jede Sprache
MailLand bietet noch kein SDK an. Die API ist JSON über HTTPS mit einem X-API-Key-Header, und die Dokumentation, verfügbar in sieben Sprachen, zeigt jede Anfrage in curl, JavaScript, Node.js, Python, PHP, C#, Java und Go.
In der EU gehostet
Die Server von MailLand laufen bei Hetzner in Deutschland, überwiegend in Nürnberg, und eine verschlüsselte Sicherungskopie liegt in Warschau, Polen. Einige Unterauftragsverarbeiter, etwa Cloudflare und Stripe, können begrenzte Daten außerhalb der EU auf Grundlage der EU-Standardvertragsklauseln verarbeiten. Der AVV führt jeden einzelnen auf.
Zum AVVFragen zur Transaktions-E-Mail-API
Gibt es einen kostenlosen Tarif?
Ja. Der Free-Tarif umfasst 1.000 E-Mails pro Monat ohne Kosten, mit derselben REST-API und demselben SMTP-Relay wie die kostenpflichtigen Tarife. Für den Start ist keine Kreditkarte nötig.
Gibt es SDKs?
Noch nicht. Die API ist JSON über HTTPS, daher funktioniert jeder HTTP-Client. Die Dokumentation enthält Beispiele zum Kopieren in curl, JavaScript, Node.js, Python, PHP, C#, Java und Go.
Wie stelle ich sicher, dass ein erneuter Versuch die E-Mail nicht doppelt sendet?
Senden Sie einen X-Idempotency-Key-Header (oder das Feld idempotencyKey) mit POST /v1/transactional/send oder send-batch. Ein erneuter Versuch mit demselben Schlüssel innerhalb von 24 Stunden liefert die ursprüngliche Antwort und versendet nichts. Nur diese beiden Endpunkte akzeptieren einen Schlüssel.
Kann eine Anfrage an viele Empfänger gehen?
Eine Transaktionsanfrage nimmt bis zu 5 Empfänger an, und jeder erhält eine eigene Kopie. Für Massenversand nutzen Sie einen Marketing-Schlüssel mit POST /v1/transactional/send-batch, der bis zu 10.000 Empfänger pro Anfrage annimmt.
Was passiert bei einem Bounce?
Ein Hard Bounce oder eine Beschwerde setzt die Adresse auf Ihre Sperrliste und wird als Ereignis an Ihren Webhook gesendet. Spätere Sendungen an diese Adresse werden abgelehnt und in rejectedRecipients aufgeführt.
Welche Versandlimits gelten?
Jeder Tarif legt ein Monatsvolumen und eine Versandrate pro Minute fest, die auf der Preisseite angegeben sind. Ein Schlüssel kann eigene, niedrigere Limits haben. Bei Überschreitung eines Limits antwortet die API mit 429 und einem Retry-After-Header.
Senden Sie noch heute Ihre erste E-Mail
Erstellen Sie ein kostenloses Konto, verifizieren Sie Ihre Domain und rufen Sie die API auf. 1.000 E-Mails pro Monat sind kostenlos.