Das Emarsys API bietet programmatischen Zugriff auf die meisten Funktionen der Emarsys Marketing Plattform; verwenden Sie es, um sich mit uns zu integrieren und Ihre Marketingkampagnen zu automatisieren.
- Dank der Integration können Sie die meisten Funktionen der Emarys Plattform direkt in Ihrer eigenen Applikation öffnen.
- Mithilfe der Automatisierung können Sie komplexe Marketingkampagnen einrichten, die ganz ohne manuelle Interaktion Ihrerseits ausgeführt werden.
Über den Emarsys Developer Hub
In diesem Hilfeportal finden Sie eine Liste aller öffentlichen API Endpunkte, der Großteil unserer technischen Inhalte befindet sich jedoch in unserem Developer Hub.
Der Developer Hub bietet Anleitungen, Ressourcen, Use Cases und interaktive Referenzen, die Ihnen bei der Integration mit der Emarsys Marketing Plattform helfen und Ihnen die persönliche Interaktion mit Ihren Kunden via E-Mail, Mobile, Social, SMS und Web ermöglichen.
Bereit, loszulegen? Hier geht es zum Emarsys Developer Hub.
Bevor Sie beginnen
Wir wollen Ihnen dabei helfen, Zeit zu sparen und häufige Fehler zu vermeiden; deshalb haben wir eine Reihe wichtiger Schritte und Top-Level-Konzepte zusammengestellt, die Sie kennen sollten, bevor Sie mit der Verwendung des Emarsys API beginnen.
Keine Angst, in wenigen Minuten werden Sie Ihren ersten erfolgreichen API Call vornehmen. Aber zuerst müssen Sie sich um ein paar organisatorische Aspekte kümmern:
- Ihr Unternehmen hat die relevanten Teile Ihrer Onboarding Journey abgeschlossen: das Daten-Onboarding und die Aktivierung des Kanals, den Sie verwenden wollen.
- Sie haben den Abschnitt Bevor Sie beginnen gelesen und wissen, wie unser RESTful API in den Grundzügen funktioniert und was es leisten kann.
- Ihr Account Owner hat unter Management > Security Settings einen API-Nutzer und den entsprechenden Secret Key eingerichtet. Weitere Informationen erhalten Sie unter API Nutzer.
- Vergewissern Sie sich, dass Ihr API Nutzer alle erforderlichen Zugriffsrechte hat. Zugriffsrechte können auf der Seite für die Sicherheitseinstellungen vergeben werden. API Nutzer haben nicht standardmäßig alle Rechte aktiviert. Wenn die Rechte nicht korrekt eingerichtet sind, können bestimmte Funktionen des API nicht verwendet werden und resultieren in einem Fehler des Typs
403 Forbidden. Weitere Informationen erhalten Sie unter API-Berechtigungssystem.
Bevor Sie das API das erste Mal verwenden, sollten Sie sich unbedingt über seine grundlegenden Konzepte, die Architektur und Best Practices informieren.
- Grundlagen lernen - Erfahren Sie mehr über die Kernkonzepte von Emarsys und das Design des RESTful API - einschließlich Authentifizierung, Ratenlimit und Requeststrukturen.
- Erste Schritte machen - Mit unserer Anleitung haben Sie Ihr System in kürzester Zeit eingerichtet.
Nachdem Sie die ersten Schritte abgeschlossen haben, gehen Sie zur Endpunkt-Referenz und testen Sie die verfügbaren Endpunkte in Echtzeit mit Ihren eigenen Daten. Unser Developer Hub enthält auch Code-Beispiele, eine umfangreiche Postman-Sammlung und Spezifikationen in den Formaten OpenAPI und RAML.
Ressourcen
Für Endpunkt-Spezifikationen und Definitionen gehen Sie direkt zum Developer Hub.
Im Developer Hub sind alle Endpunkt-Spezifikationen in den Formaten OpenAPI 2.0 (Swagger) und RAML 0.8 verfügbar, ebenso wie eine Postman-Sammlung.
| Abschnitt | Inhalt |
|---|---|
| Bevor Sie beginnen | Erfahren Sie mehr über die Emarsys Kernkonzepte und das Design unseres RESTful API. |
| Erste Schritte | Wenn Sie mit der Plattform noch nicht vertraut sind, folgen Sie unserer Schritt-für-Schritt-Anleitung. |
| Endpunkte | Sehen Sie sich die verfügbaren Endpunkte an und testen Sie diese sofort mit Ihren eigenen Daten. |
| Personalisierung |
|
| Response Codes |
|
| Anhang |
|
| Changelog | Lesen Sie unsere Release Notes und verfolgen Sie die Änderungen für das Emarsys API und den Developer Hub. |
Optionen für die interaktive Demo
Vor dem codieren - experimentieren! Um Ihnen bei der Integration zu helfen, bieten wir mehrere Optionen für das Testen der Implementierung.
Emarsys Developer Hub
Direkt im Developer Hub können Sie jeden der Endpunkte mit Ihren echten Daten testen.
Seien Sie dabei vorsichtig, das ist keine Sandbox-Funktionalität! Änderungen an Kontakt- oder Kampagnendaten haben reale Auswirkungen auf Ihren Account (wenn Sie z.B. Delete a Contact testen, wird der für den Test verwendete Kontakt tatsächlich gelöscht).
- Wählen Sie den Endpunkt aus, den Sie testen wollen.
- Klicken Sie Try it out.
- Geben Sie in der Navigationsleiste Ihre Authentifizierungsinformationen ein.
- Geben Sie die erforderlichen Parameter an.
- Klicken Sie Send request.
Ihr Request wird an unsere Server gesendet und gibt echte Daten zurück.
Auch Code-Beispiele und Spezifikationen sind immer zur Hand: Gehen Sie auf der Endpunkt-Seite zum Tab Code Generation; darauf finden Sie Code-Beispiele für jeden Endpunkt und in mehreren Sprachen. Mit einem einfachen Copy&Paste-Vorgang können Sie diese in Ihren Code einfügen.
Auch Curl-Befehle sind in den Code-Beispielen verfügbar.
Postman-Sammlung
Wenn Sie Postman bevorzugen, laden Sie unsere kategorisierten Bibliotheken herunter; in diesen sind alle Endpunkte mit Beispielen enthalten.
Wenn Sie Postman verwenden, müssen Sie den Wert für den WSSE Header manuell erstellen und in den Header X-WSSE einfügen.
Seite für die API Demo
Wir haben eine Demo-Seite eingerichtet, auf der Sie die API-Funktionen ausprobieren können. Die Seite bietet eine grafische Benutzeroberfläche für das Experimentieren mit API Requests und den entsprechenden Parametern. Danach werden die Responses angezeigt, damit die Nutzer wissen, was sie erwarten dürfen.
- Um auf die Demo-Umgebung zuzugreifen, gehen Sie zu https://api.emarsys.net/api-demo.
- Um zu überprüfen, ob Sie gültige Zugangsdaten verwenden, machen Sie einen Test-Request und schauen Sie, welche Sprachen verfügbar sind. Gehen Sie dafür zum Tab Contact Fields. Lassen Sie das Feld für den Language code leer und klicken Sie OK. Der Response wird rechts auf derselben Seite angezeigt, gemeinsam mit weiteren Informationen zum Request. Die nachstehende Tabelle enthält die möglichen Responses und Fehlerursachen.
| Response (replyCode, replyText) | Mögliche Ursache | Mögliche Lösung |
|---|---|---|
| 0, OK | Sie waren erfolgreich und Ihre Credentials wurden akzeptiert. | Die Liste der Sprachen sollte angezeigt werden. |
| 1, Unauthorized | Mit Ihren Credentials stimmt etwas nicht. | Überprüfen Sie nochmals Ihre Zugangsinformationen. |
| No response at all |
|
|
Der Response auf Ihren Request wird immer rechts oben auf der Seite angezeigt; nach dem Senden eines Requests müssen Sie möglicherweise nach oben scrollen, um den Response zu sehen.
Befehlszeile
API Retries
In Workflows, die API Calls verwenden, sollen Sie einen Retry-Mechanismus installieren.
Fehlermeldungen nach einem fehlgeschlagenen API Call können ihre Ursache in vorübergehenden Verbindungsproblemen des lokalen oder globalen Netzwerks haben. Eine Reihe von Fehlern und Ausfällen, die Auswirkungen auf unsere Kommunikation haben, können außerhalb unserer Systeme auftreten. In diesen Fällen lässt sich das Problem häufig mit einem erneuten Versuch lösen.
Ein gutes Beispiel für einen Workflow, bei dem ein Retry-Mechanismus helfen kann, ist, wenn Sie auf einen Call den Response "HTTP 503 / The system is overloaded for this resource." erhalten.
Terminieren Sie den erneuten Versuch und achten Sie darauf, dass dieser nicht direkt nach Rückgabe des Fehlers HTTP 503 erfolgt. Verzögern Sie den API Retry um 3-4 Minuten oder wählen Sie einen Zeitraum, in der es auf Ihrer Seite keine Aktivitäten gibt, damit Sie nicht mehrere Calls gleichzeitig senden.