E-Mail-API und Webhooks
Neben SMTP hat 2mail eine REST-API: Sie senden eine Nachricht mit einem einzigen HTTPS-Aufruf, fragen danach ihren Status ab und lassen jedes Ereignis — zugestellt, gebounced, geöffnet — automatisch per Webhook an Ihr eigenes System übermitteln.
Diese Seite beschreibt, was die API tut und wie der Zugang funktioniert. Die vollständige Referenz mit allen Feldern und Beispielaufrufen ist offen: Sie können sie lesen, bevor Sie ein Konto haben. Arbeiten Sie in PHP, nimmt Ihnen das offizielle SDK die HTTP-Arbeit ab.
Was Sie damit bauen
Senden aus Ihrer Anwendung
Ein POST mit Absender, Empfänger, Betreff und Inhalt. Sie können eine Nachricht auch vorausplanen und pro Nachricht festlegen, ob Öffnungen gemessen werden. Die Antwort enthält sofort eine ID, mit der Sie die Nachricht später wiederfinden.
Den Status einer Nachricht abfragen
Mit dieser ID fragen Sie ab, ob die Nachricht in der Warteschlange steht, gesendet wurde oder fehlgeschlagen ist — inklusive Grund bei einem Fehler. So müssen Sie nicht in Logdateien suchen, wenn ein Kunde wegen einer bestimmten E-Mail anruft.
Ereignisse automatisch empfangen
Registrieren Sie eine URL und 2mail übermittelt jedes Ereignis dorthin, sobald es eintritt: zugestellt, verzögert, gebounced, abgewiesen, geöffnet oder fehlgeschlagen. Kein Polling, keine Warteschlange, die Sie selbst leeren müssen.
Ein Schlüssel pro Anwendung
Jede Anwendung erhält einen eigenen Schlüssel, den Sie separat widerrufen können. Ein Sendeschlüssel darf ausschließlich senden und den Status seiner eigenen Nachrichten abfragen — sonst nichts, auch keine anderen Daten Ihres Kontos.
Eine Nachricht senden
Der Aufruf ist bewusst klein gehalten: ein Schlüssel im Authorization-Header und ein JSON-Body. Die Absenderadresse muss auf einer Ihrer eigenen Domains liegen.
POST https://www.2mail.eu/2mail/api/v1/messages Authorization: Bearer 2m_live_UW_SLEUTEL Content-Type: application/json { "from": "no-reply@ihredomain.be", "to": "kunde@beispiel.be", "subject": "Ihre Bestellung wurde versandt", "html": "<p>Vielen Dank für Ihre Bestellung.</p>" }
202 Accepted { "id": "4f3c…", "status": "queued" }
Sie erhalten eine 202 mit einer ID zurück. Das bedeutet angenommen, nicht zugestellt — die Zustellung selbst verfolgen Sie mit einer Statusabfrage oder, besser, mit einem Webhook.
Lieber kein HTTP schreiben? Das PHP SDK
composer require jaanbv/2mail-php-api $api = new TwoMail($apiKey); $api->sendMail( 'no-reply@ihredomain.be', 'kunde@beispiel.be', 'Ihre Bestellung wurde versandt', '<p>Vielen Dank für Ihre Bestellung.</p>' );
Für PHP gibt es einen offiziellen Client, der jeden Endpunkt oben abdeckt. Derselbe Aufruf wird zu vier Zeilen, und Sie müssen keine curl-Optionen, JSON-Kodierung oder Fehlerbehandlung selbst pflegen.
Das SDK hält Absenderadresse und Anzeigename auseinander, prüft Webhook-Signaturen für Sie und gibt jedem Fehlercode eine eigene Exception — damit Sie auf den Fehlertyp reagieren können statt auf einen Text, der morgen anders formuliert sein kann.
Webhooks: die Zustellung verfolgen Sie passiv
Ein Webhook ist eine URL von Ihnen, die wir aufrufen, sobald mit Ihrer Nachricht etwas geschieht. Das ist genauer als regelmäßiges Abfragen des Status, und Sie bemerken einen Bounce innerhalb einer Minute statt bei der nächsten Runde.
POST https://ihredomain.be/webhooks/2mail X-2mail-Event: bounced X-2mail-Signature: t=1755417600,v1=<hmac-sha256> { "event": "bounced", "timestamp": "2026-08-17T10:04:11+02:00", "recipient": "kunde@beispiel.be", "message_id": "<…>", "detail": "550 5.1.1 unknown", "code": "5.1.1" }
// $secret: eenmalig getoond bij aanmaak $body = file_get_contents('php://input'); parse_str(strtr($_SERVER['HTTP_X_2MAIL_SIGNATURE'], ',', '&'), $p); $ok = hash_equals( hash_hmac('sha256', $p['t'] . '.' . $body, $secret), $p['v1'] );
Jeder Aufruf ist signiert
Wir senden eine Signatur im Header X-2mail-Signature mit, berechnet mit HMAC-SHA256 über den Zeitstempel und den rohen Body, mit einem Schlüssel, den nur Sie und wir kennen. Prüfen Sie diese Signatur, bevor Sie dem Inhalt vertrauen: ohne Prüfung kann jeder, der Ihre URL kennt, Ereignisse erfinden. In PHP müssen Sie das nicht selbst schreiben: das SDK erledigt die Prüfung in einer Zeile, inklusive der Zeitfensterprüfung, die die Wiederverwendung eines abgefangenen Aufrufs verhindert.
Fehlgeschlagene Aufrufe werden wiederholt
Antwortet Ihr Endpunkt nicht mit 2xx, versuchen wir es erneut in wachsenden Abständen — nach einer Minute, fünf Minuten, einer halben Stunde, zwei Stunden und sechs Stunden. Im Portal sehen Sie pro Versuch den Antwortcode und die Fehlermeldung, sodass Sie einen fehlerhaften Endpunkt aufspüren können, ohne uns zu kontaktieren.
Welche Ereignisse
Zugestellt, verzögert, gebounced, abgewiesen, geöffnet, angenommen und fehlgeschlagen. Sie wählen pro Webhook, welche Typen Sie empfangen möchten, oder lassen es leer für alle.
Schlüssel und Zugang
Ein API-Schlüssel wird einmalig angezeigt und danach nur als Hash gespeichert. Verlieren Sie ihn, widerrufen Sie ihn und erstellen einen neuen — wir können ihn nicht erneut anzeigen.
Sendeschlüssel
Gehört zu einem Postfach und darf genau zwei Dinge: eine Nachricht senden und den Status seiner eigenen Nachrichten abfragen. Jeder andere Endpunkt antwortet mit 403. Das ist der Schlüssel, den Sie in einen Onlineshop oder eine Anwendung einbauen.
Verwaltungsschlüssel
Für alle, die Postfächer, Domains und SMTP-Benutzer programmatisch anlegen möchten — zum Beispiel ein Partner, der Kunden in Eigenregie ausrollt. Diesen Schlüssel erstellen Sie im Portal, nicht über die API.
Sendeschlüssel erstellen und verwalten Sie selbst im Kundenportal unter Einstellungen. Dort sehen Sie auch, wann jeder Schlüssel zuletzt verwendet wurde.
Die vollständige Dokumentation
Jeder Endpunkt, jedes Feld und jeder Fehlercode steht in der interaktiven Referenz. Dort können Sie auch direkt ausprobieren: klicken Sie auf Authorize, fügen Sie Ihren Schlüssel ein und führen Sie einen echten Aufruf aus.
Die Spezifikation ist öffentlich und in Postman oder Insomnia importierbar oder zum Generieren eines Clients nutzbar. Auch die interaktive Referenz ist frei zugänglich — einen Schlüssel brauchen Sie erst, wenn Sie einen Aufruf tatsächlich ausführen möchten.
Loslegen
Die API ist in jedem 2mail-Paket enthalten; es gibt keine separate Lizenz oder ein Modul dafür. Haben Sie eine Frage zu einer Anbindung oder möchten Sie wissen, ob Ihr Szenario passt, lassen Sie es uns wissen — wir denken gerne mit, bevor Sie zu bauen beginnen.