Erste Schritte mit E-Mail

Die Vonage Messages API unterstützt E-Mail als Kanal und ermöglicht es Ihnen, Transaktions-E-Mails mit demselben API-Vertrag zu versenden, den Sie bereits für andere Messaging-Kanäle verwenden. Mit einer einzigen Integration können Sie Ihre gesamte ausgehende Kommunikation verwalten, ohne einen separaten E-Mail-Anbieter zu Ihrem Stack hinzufügen zu müssen.

In diesem Leitfaden erfahren Sie alles, was Sie brauchen, um Ihre erste E-Mail über die Messages API zu versenden.

Voraussetzungen

Bevor Sie beginnen, vergewissern Sie sich, dass Sie die folgenden Informationen haben:

• A Vonage API-Konto
• Ihr API-Schlüssel und Ihr API-Geheimnis, die über das Vonage API-Dashboard verfügbar sind
• Eine verifizierte Senderdomäne - siehe Einrichtung der Domänenauthentifizierung unter
• Beta-Zugang zum E-Mail-Kanal - kontaktieren Sie Ihren Account Manager

E-Mail-Onboarding

Führen Sie folgende Schritte aus, um an Bord zu kommen:

1. Geben Sie Ihrem Account Manager die folgenden Informationen:
   • Ihr Vonage API-Schlüssel
   • Die benutzerdefinierte(n) Domäne(n), von der/denen aus Sie E-Mails senden werden (z. B. IhreDomäne.com)
   • Ihre bevorzugte Region für die Domainüberprüfung: USA, EU oder APAC

2. Ihr Account Manager leitet die Informationen an den Produktmanager weiter, der das Onboarding-Verfahren einleitet.
3. Vonage stellt eine Reihe von DNS-Einträgen zur Verfügung, die Sie zur DNS-Konfiguration Ihrer Domain hinzufügen müssen. Siehe Einrichtung der Domänenauthentifizierung für die vollständige Liste der Datensätze und deren Funktionen.
4. Sobald Sie Ihre DNS-Einträge aktualisiert haben, bestätigen Sie dies mit Ihrem Account Manager. Die DNS-Überprüfung kann bis zu 72 Stunden in Anspruch nehmen.
5. Fügen Sie Ihre DNS-Einträge umgehend hinzu, die Übertragung kann bis zu 72 Stunden dauern. Wenn es länger als erwartet dauert, empfehlen wir Ihnen, neue DNS-Einträge für Ihre Domäne zu erstellen.
6. Wenn die Verifizierung abgeschlossen ist, benachrichtigt Vonage Ihren Account Manager, und Sie können mit dem Versand von E-Mails über die Messages API beginnen.

Einrichtung der Domänenauthentifizierung

Bevor Sie E-Mails senden können, müssen Sie Ihre Senderdomäne authentifizieren. Die Domain-Authentifizierung verbessert die Zustellbarkeit von E-Mails und ermöglicht es Mailbox-Anbietern zu verifizieren, dass Vonage berechtigt ist, E-Mails in Ihrem Namen zu versenden.

Die Authentifizierung wird durch Hinzufügen von DNS-Einträgen zur DNS-Konfiguration Ihrer Domäne abgeschlossen. Diese Einträge ermöglichen:

• SPF (Sender Policy Framework) - autorisiert die Versandinfrastruktur von Vonage, im Namen Ihrer Domain zu versenden.
• DKIM (DomainKeys Identified Mail) - signiert ausgehende E-Mails kryptografisch, damit die empfangenden Server überprüfen können, dass der Inhalt nicht manipuliert wurde.
• DMARC (Domain-based Message Authentication, Reporting & Conformance) - definiert die Richtlinien für die Behandlung von Authentifizierungsfehlern und liefert Berichte.

Große Mailbox-Anbieter wie Google, Microsoft und Yahoo verlassen sich auf diese Mechanismen, um zu entscheiden, ob E-Mails zugestellt, abgelehnt oder als Spam markiert werden sollen.

Zu konfigurierende DNS-Einträge

Vonage stellt die genauen DNS-Datensatzwerte während des Onboardings zur Verfügung. Die folgende Tabelle zeigt die Struktur und den Typ der einzelnen Einträge, die Sie hinzufügen müssen:

Senden Sie Ihre erste E-Mail

Sobald Ihre Domain verifiziert ist, können Sie E-Mails über die Messages API versenden.

Erstellen einer Vonage-Applikation

Um die Messages API zu nutzen, benötigen Sie eine Vonage Application mit aktivierter Messages-Funktion. Die Anwendung enthält Ihre Webhook-Konfiguration und Authentifizierungsdaten.

1. Gehen Sie im Vonage Dashboard zu Create an Application.
2. Geben Sie Ihrer Anwendung einen Namen.
3. Klicken Sie auf Öffentlichen und privaten Schlüssel generieren. Ihre private Schlüsseldatei wird automatisch heruntergeladen - bewahren Sie sie sicher auf, da sie nicht erneut heruntergeladen werden kann.
4. Unter FähigkeitenNachrichten aktivieren.
5. Setzen Sie Ihre Eingangs-URL und Status-URL auf die Webhook-Endpunkte in Ihrer Anwendung. Wenn Sie diese noch nicht haben, können Sie Platzhalter-URLs verwenden und sie später aktualisieren.
6. Klicken Sie auf Neue Anwendung generieren.

Weitere Informationen finden Sie unter Erstellen einer Vonage-Applikation.

Legen Sie Ihre ersetzbaren Werte fest

Die Code-Beispiele in diesem Leitfaden verwenden die folgenden Variablen. Ersetzen Sie die einzelnen Variablen durch Ihre tatsächlichen Werte, bevor Sie die Beispiele ausführen.

Erzeugen eines JWT

Die Messages API verwendet JSON-Web-Tokens (JWTs) zur Authentifizierung. Generieren Sie ein JWT mit Ihrer Application ID und Ihrem privaten Schlüssel.

Eine Text-E-Mail senden

Verwenden Sie die folgende Anfrage, um eine einfache Text-E-Mail zu senden:

{
  "channel": "email",
  "from": "sender@example.com",
  "to": "recipient@example.com",
  "message_type": "text",
  "text": "Email body text",      
  "email": {
    "subject": "Email subject"  
  }
}

Wenn die Anfrage erfolgreich war, erhalten Sie eine Antwort, die die message_uuid:

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Eine HTML-E-Mail senden

Um eine E-Mail mit HTML-Inhalt zu versenden, setzen Sie message_type zu "html" und geben Sie Ihre HTML-Auszeichnung in das Feld body ein:

{
  "channel": "email",
  "from": "sender@example.com",
  "to": "recipient@example.com",
  "message_type": "html",
  "html": {
    "body": "<p>Email body html</p>"
  },      
  "email": {
    "subject": "Email subject"  
  }
}

E-Mail-Größenbeschränkungen

Der E-Mail-Text hat eine maximale Größe von 100 KB pro API-Anfrage. Wenn der E-Mail-Text diese Grenze überschreitet, wird bei der Anfrage ein Fehler ausgegeben. Stellen Sie sicher, dass Ihr E-Mail-Text innerhalb der unterstützten Größenbeschränkung bleibt.

Zusätzlich zur Begrenzung des E-Mail-Textes erzwingt die Messages API auf Netzwerkebene eine Beschränkung der Gesamtgröße der Nutzdaten auf 200 KB. Beachten Sie diese Grenzen, um eine zuverlässige Nachrichtenzustellung zu gewährleisten.

Lieferstatus prüfen

Nach dem Versand einer E-Mail sendet Vonage Aktualisierungen des Zustellungsstatus an die in Ihrer Vonage Application konfigurierte Status-URL. Jede Aktualisierung ist eine POST-Anfrage, die die message_uuid und ein Statusfeld.

Die wichtigsten Status für den E-Mail-Kanal sind:

E-Mail-Preise

Die Preise für die E-Mail-API sind abonnementbasiert und in sechs Stufen erhältlich. Jede Stufe umfasst eine feste Anzahl von E-Mails. Sobald Sie die in Ihrem Tarif enthaltene Anzahl an E-Mails verbraucht haben, fallen Gebühren pro E-Mail an. Aktuelle Preisinformationen erhalten Sie von Ihrem Account Manager.

Weitere Informationen

• Verstehen von E-Mail-Nachrichten
• Messages API-Referenz