Product
Gleiche API, neue Tricks: Ereignisbenachrichtigungen rechtzeitig per Webhook erhalten
Bei der Arbeit an diesem API-Update sind uns einige Dinge durch den Kopf gegangen – und Ihnen vielleicht auch:
- Webhooks sind großartig. Alle sollten sie nutzen.
- Versanddaten direkt aus meinen Nachrichten abzurufen, spart Zeit.
Ehrlich gesagt gibt es die Webhook-API von Mailgun schon sehr lange. Aber mit diesem Update haben Sie mehr Möglichkeiten, mit uns zu kommunizieren und detailliert nachzuverfolgen, was mit Ihren Nachrichten passiert.
Sehen wir uns die Details an.
Was gibt es Neues?
Worum geht es bei diesem Update?
Mailgun hilft Ihnen dabei, Benachrichtigungen genau im richtigen Moment zu erhalten, sodass Sie sofort sehen, wenn mit Ihrer Nachricht etwas passiert ist. Sie haben die Wahl: Nutzen Sie Event-Polling über die Events API, oder lassen Sie sich Push-Ereignisse über die Webhook-API senden. Diese Warnungen enthalten die gleichen Daten wie die Events API und werden per HTTP POST an Ihre URL/URLs gesendet.
Ab sofort erhalten Sie Folgendes:
- Nutzdaten im Format „Application/JSON“
- Bis zu drei URLs pro Ereignis
- Daten zu den folgenden Ereignistypen:
- opened – jedes Mal, wenn ein Nutzer eine Ihrer Nachrichten öffnet
- clicked – jedes Mal, wenn ein Nutzer auf einen Link in Ihren Nachrichten klickt
- unsubscribed – wenn sich ein Nutzer abmeldet, sei es von allen Nachrichten, einem bestimmten Tag oder einer Mailingliste
- complained – wenn ein Nutzer eine Ihrer E-Mails als Spam meldet. Beachten Sie, dass nicht alle ESPs dieses Feedback bereitstellen.
- delivered – wenn der Empfänger-E-Mail-Server meldet, dass er die Nachricht angenommen hat.
- permanent_fail – es gibt verschiedene Gründe, warum Mailgun Zustellversuche einstellt und Nachrichten verwirft. Dazu gehören Hard Bounces, Nachrichten, die ihr Wiederholungslimit erreicht haben, Adressen mit vorherigen Abmeldungen/Bounces/Beschwerden oder Adressen, die von einem ESP abgelehnt wurden.
- temporary_fail – wenn eine Nachricht vorübergehend von einem ESP abgelehnt wird
Der Vorteil daran ist, dass Ihr Code für die Geschäftslogik für beide Optionen verwendet werden kann. Der Unterschied liegt darin, wie Sie sich mit Mailgun verbinden. Und da jedes Ereignis eine eigene, eindeutige ID hat, können Sie Ereignisse problemlos abrufen und anhand dieser eindeutigen ID sortieren, falls Ihr http-Endpunkt aus irgendeinem Grund ausfällt. Natürlich empfehlen wir stets, Webhooks asynchron zu verarbeiten, damit Lastspitzen bei den Ereignissen kein Problem darstellen.
Wie nutze ich die API?
Sehen wir uns nun an, wie Sie eine Domain mit dem Webhook „clicked“ konfigurieren. Es ist im Grunde ein einstufiger Prozess, den Sie abschließen können, indem Sie eine oder mehrere URLs mit curl oder in Ihrer bevorzugten Programmiersprache über unsere HTTP-API einrichten.
Zum Beispiel mit dem curl-Befehl:
curl -s --user ‘api:YOUR_API_KEY’
https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks
-X POST
-F id=clicked
-F url="https://api.your.domain.com/v1/mg/clicked"
-F url="https://api.your.domain.com/v2/mg/clicked"
-F url="https://api.partner.com/v1/you/clicked"
Hierbei sollte "id" der Name des Webhooks sein (nur ein Webhook pro Anfrage) und "url" Ihre URL angeben (bis zu drei URLs pro Anfrage).
Und die Antwortnachricht:
{
"message": "Webhook has been created",
"webhook": {
"urls": [
"https://api.your.domain.com/v1/mg/clicked",
"https://api.your.domain.com/v2/mg/clicked",
"https://api.partner.com/v1/you/clicked"
]
}
}
Die unter Ihrer URL/Ihren URLs empfangenen Daten sollten wie folgt aussehen:
{
“signature”:
{
"timestamp": "1529006854",
"token": "a8ce0edb2dd8301dee6c2405235584e45aa91d1e9f979f3de0",
"signature": "d2271d12299f6592d9d44cd9d250f0704e4674c30d79d07c47a66f95ce71cf55"
}
“event-data”:
{
"timestamp": 1529006854.329574,
"id": "DACSsAdVSeGpLid7TN03WA",
"event": "delivered",
"tags": [...],
"user-variables": {...},
"message": {
"headers": {
"message-id": "20180618211821.example.org"
}
},
…
}
}
Der "event-data"-Teil entspricht der Rückgabe der Events API und enthält: Ereignis-Zeitstempel, eindeutige Ereignis-ID, Name des Ereignisses, Nachrichten-ID, Ihre Tags und Variablen usw. Als Best Practice sollten Sie nicht vergessen, den "signature"-Teil zu überprüfen (siehe hier wie das geht).
Das war’s. Ganz einfach, oder?
Kann ich Ereignisse an mehrere Endpunkte senden?
Ja, dies ist möglich. Wenn Sie Ihre Anwendung auf eine neue Version migrieren oder Ereignisse an Ihre Partnerseite senden müssen, ist dies für bis zu drei Endpunkte möglich.
Wenn Sie sehen möchten, wie Ihr Ereignis aussieht, oder eine Frage an unser Support-Team haben, können Sie ganz einfach einen Webhook mit einer temporären URL zu unserem Request Bin einrichten unter http://bin.mailgun.net und gleichzeitig Ereignisse abrufen.
Hier sehen Sie, was passiert, wenn Sie zusätzlich eine Test-API mit folgendem curl-Befehl verwenden:
curl -s --user ‘api:YOUR_API_KEY’ \
https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/HOOK_NAME/test \
-X PUT \
-F url=YOUR_URL
Hier ist "url" Ihre URL (eine pro Anfrage) und "HOOK_NAME" der Name des Webhooks (siehe obige Liste – ebenfalls einer pro Anfrage).
Und die Antwortnachricht:
{
"code" : null,
"message": "{\"message\":\"Post received. Thanks!\"
}
Hier gibt "code" den von Ihrer Seite empfangenen HTTP-Code an (null bedeutet 200 OK) und "message" zeigt den empfangenen HTTP-Body von Ihrer Seite oder die Fehlermeldung an
Ich bin Mailgun-Nutzer – kann ich problemlos auf die neue API umsteigen?
Ja. Alle veralteten Webhooks müssen auf diese neue Version umgestellt werden. Der Endpunkt der veralteten Webhook-API ist seit dem 15. April 2023 schreibgeschützt. Damit ist der im März 2022 begonnene Prozess der Außerbetriebnahme abgeschlossen.
Produktupdates sind wichtig. Als E-Mail-Unternehmen sind wir natürlich bestens darin geübt, Ihnen Updates zu senden, um Sie auf dem Laufenden zu halten. Möchten Sie mehr über das Warum und Wie hinter unseren Neuerungen erfahren? Abonnieren Sie unseren Newsletter für weitere Inhalte wie diesen.
