So senden Sie E-Mails mit PHP mit Twilio SendGrid und Mezzio

Veröffentlicht: 2021-03-24

E-Mail ist nach wie vor ein wichtiges Kommunikationsmittel. Um Ihnen zu helfen, E-Mails besser zu nutzen, werde ich Ihnen zeigen, wie Sie E-Mails mit dem Mezzio-Framework von PHP und der API von Twilio SendGrid senden.

Insbesondere lernen Sie, wie Sie E-Mails mit Klartext- und HTML-Texten senden, einschließlich eines PDF-Anhangs. Außerdem erfahren Sie, wie Sie die Transaktionsvorlagenfunktion von Twilio SendGrid verwenden, um das Erstellen von E-Mail-Texten sowohl für das Entwicklungsteam als auch für jedes andere Team in Ihrer Organisation zu vereinfachen.

Klingt gut? Lass uns anfangen.

Schnelle Anwendungsübersicht

Um dieses Tutorial aussagekräftiger zu gestalten, stellen Sie sich vor, dass der Code, den wir schreiben werden, Teil eines fiktiven Online-E-Commerce-Shops namens The Little PHP Shop ist, der mit Mezzio erstellt wurde – insbesondere der Teil unmittelbar nachdem ein Kunde einen Kauf getätigt hat. An diesem Punkt im Benutzerfluss erhält der Kunde eine E-Mail, in der ihm für seinen Kauf gedankt wird, und fügt eine PDF-Rechnung für seine Unterlagen bei.

Wir werden eine Handler-Klasse erstellen, um die E-Mail nach dem Kauf zu senden, die Kaufdetails von einer vom Kunden abgeschlossenen Bestellung erhält. Mit diesen Kaufinformationen verwendet die Handler-Klasse dann mehrere Klassen in der SendGrid-PHP-API, um die Kaufbestätigungs-E-Mail zu erstellen und zu senden.

Die wichtigsten davon sind „SendGrid\Mail\Mail“ und „\SendGrid“. „SendGrid\Mail\Mail“ ist das Objekt, das alle Eigenschaften für eine E-Mail-Nachricht speichert, die wir über Twilio SendGrid senden. Das „SendGrid“-Objekt bildet die Transportschicht und erleichtert das Versenden von E-Mails über Twilio SendGrid.

Voraussetzungen

Um dieses Tutorial abzuschließen, benötigen Sie die folgenden 4 Dinge in Ihrer lokalen Entwicklungsumgebung:

  1. Twilio SendGrid-Konto
  2. PHP 7.4 mit installierten und aktivierten Erweiterungen cURL , mbstring und Open SSL
  3. Composer global installiert
  4. cURL

Erstellen Sie ein Gerüst für die Mezzio-Anwendung

Wir müssen zuerst die Basisanwendung erstellen. Dazu verwenden wir wie immer das Mezzio-Skelett , um es für uns zu tun. Nachdem wir die Basisanwendung erstellt haben, wechseln wir in das neu erstellte Projektverzeichnis. Führen Sie dann die folgenden Befehle in Ihrem Terminal aus und folgen Sie den Eingabeaufforderungen für den ersten:

Installieren Sie die erforderlichen Abhängigkeiten

Wenn das Projekt ein Gerüst ist, müssen wir 3 zusätzliche Abhängigkeiten hinzufügen, um das Projekt abzuschließen. Diese sind:

  • Die PHP-API-Bibliothek von Twilio SendGrid für die Interaktion mit der Twilio SendGrid-API
  • PHP-HTTP-Client zum Senden von HTTP-Anforderungen
  • PHP Dotenv zum Speichern und Abrufen von Umgebungsvariablen

Um sie zu installieren, führen Sie den folgenden Befehl in Ihrem Terminal aus:

Initialisieren Sie PHP Dotenv

Wenn die Abhängigkeiten installiert sind, laden wir PHP Dotenv, damit es die in „.env“ festgelegten Variablen liest und sie PHP als Umgebungsvariablen zur Verfügung stellt. Fügen Sie dazu den folgenden Code in „public/index.php“ direkt nach „require supplier/autoload.php“ ein.

Fügen Sie Ihre Twilio SendGrid-Kontodetails hinzu

Jetzt müssen Sie die Anwendung mit Ihrem SendGrid-API-Schlüssel versorgen. Navigieren Sie dazu nach der Anmeldung bei Twilio SendGrid zu „Settings -> API Keys . " Einmal da:

  1. Klicken Sie auf „ API-Schlüssel erstellen“, um einen API-Schlüssel zu erstellen
  2. Geben Sie dem neuen API-Schlüssel einen Namen, akzeptieren Sie die standardmäßige API-Schlüsselberechtigung „ Vollzugriff “ und klicken Sie auf „ Erstellen und anzeigen “ .

Klicken Sie mit dem erstellten API-Schlüssel auf den Schlüssel und kopieren Sie ihn. Klicken Sie dann auf „ Fertig “ . ”

Fügen Sie danach zwei weitere Schlüssel zur Datei hinzu: „SENDGRID_DEFAULT_SENDER_ADDRESS“ und „SENDGRID_DEFAULT_SENDER_NAME“. Wie die Namen andeuten, sind dies die E-Mail-Adresse und der Name, die wir für alle E-Mails verwenden, die von unserer Anwendung gesendet werden, sofern sie nicht überschrieben werden.

Hinweis: Stellen Sie dazu unter Sender Authentication sicher, dass in der Tabelle „Single Sender Verification“ „Verified“ steht.

Legen Sie Anwendungs-Mail-Konfigurationsdetails fest

Zusätzlich zum Twilio SendGrid-API-Schlüssel werden wir einige andere globale E-Mail-Konfigurationseinstellungen speichern. Insbesondere werden wir eine Absender- und Antwort-E-Mail-Adresse und einen Namen festlegen, die wir in jeder E-Mail-Nachricht verwenden. Auf diese Weise müssen wir sie nicht jedes Mal neu einstellen.

Wir werden auch zwei E-Mail-Textvorlagen erstellen: eine für Klartext-E-Mails und eine für HTML-E-Mails. Erstellen Sie dazu in „config/autoload“ eine neue Datei mit dem Namen „mail.global.php“ und fügen Sie darin den folgenden Code hinzu.

Erstellen Sie eine Klasse, um ein Mail-Objekt zu instanziieren

Lassen Sie uns nun, nachdem die wichtigsten Anwendungskonfigurationsdetails festgelegt wurden, eine Klasse erstellen, die ein einfaches E-Mail-Objekt mit den festgelegten Standardeigenschaften instanziiert. Erstellen Sie dazu in einem neuen Verzeichnis „src/App/src/Mailer“ eine neue Datei namens „SendGridMailMessageFactory.php“ und fügen Sie darin den folgenden Code hinzu.

Wenn wir die Klasse aufrufen, hat sie Zugriff auf den Dependency Injection (DI)-Container der Anwendung, aus dem sie die Konfigurationsdetails abruft, die wir in „config/autoload/mail.global.php“ gespeichert haben.

Danach instanziiert es ein neues „SendGrid\Mail\Mail“-Objekt und legt die „from“- und „reply to“-Details fest, indem es die entsprechenden Konfigurationsdetails an Aufrufe der „Mail“-, „setFrom“- bzw. „setReplyTo“-Methoden übergibt. Danach wird das instanziierte „Mail“-Objekt zurückgegeben.

Um es zu verwenden, müssen Sie es jedoch beim DI-Container registrieren. Fügen Sie dazu in „src/App/src/ConfigProvider“ den folgenden Eintrag zum „factorys“-Element in dem Array hinzu, das von der „getDependencies“-Methode zurückgegeben wird.

Erstellen Sie einen Handler zum Senden von E-Mails

Als nächstes müssen wir eine Handler-Klasse zum Verfassen und Senden von E-Mails erstellen. Dazu verwenden wir die CLI-Tools von Mezzio , die über Composer verfügbar sind, indem wir den folgenden Befehl ausführen.

Das Ausführen des obigen Befehls bewirkt vier Dinge für uns:

  1. Erzeugt eine neue Handler-Klasse, „src/App/Handler/EmailSenderHandler.php “
  2. Erstellt eine Factory-Klasse zum Instanziieren der Handler-Klasse „src/App/Handler/EmailSenderHandlerFactory.php“.
  3. Erstellt eine Vorlagendatei („src/App/templates/app/email-sender.html.<ext>“), die wir nicht benötigen . Der Dateiname „<ext>“ wird durch die Vorlagen-Engine bestimmt , die Sie während der Phase „Projekt erstellen“ ausgewählt haben.
  4. Registriert die neue Handler-Klasse als Dienst im DI-Container, indem ein Eintrag zu „config/autoload/mezzio-tooling-factories.global.php“ hinzugefügt wird.

Refactoring des Handlers zum Senden von E-Mails

Nachdem „EmailSenderHandler.php“ erstellt wurde, müssen wir es jetzt umgestalten, damit es E-Mails senden kann. Dazu überarbeiten wir zunächst den Konstruktor von „EmailSenderHandler“ und ersetzen den Parameter „TemplateRendererInterface“ durch drei neue Parameter. Diese werden 3 neue Klassenmitgliedsvariablen initialisieren:

  • Ein „\SendGrid\Mail\Mail“-Objekt
  • Ein „\SendGrid“-Objekt
  • Ein Array mit den erforderlichen Konfigurationsdetails

Sie können den überarbeiteten Konstruktor im folgenden Beispiel zusammen mit den zugehörigen Klassenmitgliedsvariablen sehen. Ersetzen Sie die vorhandene Klassenmembervariable und den Konstruktor durch diesen Code.

Hinweis: Als nächstes müssen wir die „handle“-Methode umgestalten. Ersetzen Sie den vorhandenen Inhalt der „handle“-Methode „EmailSenderHandler“ durch den folgenden Code, und lassen Sie uns dann Schritt für Schritt durchgehen, was es tut.

Es beginnt mit der Verwendung von „$request->getParsedBody()“, um alle im Anfragetext bereitgestellten Parameter abzurufen, die ein assoziatives Array zurückgeben und „$details“ initialisieren. Mit den verfügbaren Parametern ruft es die „addTo“-Methode des „SendGrid\Mail\Mail“-Objekts auf, um den Empfänger der E-Mail festzulegen, wobei die E-Mail-Adresse und der Name des Empfängers in den ersten beiden Argumenten und ein Array von Ersetzungen im dritten Argument übergeben werden.

Mit Ersetzungen können Sie E-Mail-Nachrichten für jeden Empfänger anpassen. In Klartext-E-Mails ist jede Zeichenfolge, die unmittelbar von Bindestrichen umgeben ist, z. B. „-Vorname-“, eine Substitution. In HTML-E-Mails wird die Handlebars-Syntax verwendet , die Zeichenfolgen in doppelte Klammern einschließt, z. B. „{{ first_name }}“.

Als Nächstes legen wir den Betreff der Nachricht fest und fügen einen Klartext- und einen HTML-Nachrichtentext hinzu. Damit ist unsere E-Mail versandbereit. Also verwenden wir das „SendGrid“-Objekt, „$this->mailer“, um es zu senden, und initialisieren eine neue Variable, „$response“, mit der Antwort auf den Versuch, die Nachricht zu senden. Schließlich geben wir ein JsonResponse-Objekt zurück , das den Statuscode und den Text der Antwort enthält.

Hinweis: Refaktorieren Sie die __invoke-Methode von EmailSenderHandlerFactory

Nachdem wir die Umgestaltung von „EmailSenderHandler“ abgeschlossen haben, müssen wir „EmailSenderHandlerFactory“ umgestalten. Dadurch wird „EmailSenderHandler“ korrekt instanziiert. Ersetzen Sie dazu die vorhandene Definition der Methode „__invoke`“ durch den folgenden Code.

Dies ruft ein „\SendGrid\Mail\Mail“-Objekt aus dem DI-Container ab, das mit den Absender- und Antwort-E-Mail-Details vorinitialisiert ist, und initialisiert ein neues Objekt mit dem Namen „$message“. Anschließend instanziiert es ein neues „SendGrid“-Objekt mit dem Namen „$mailer“ zum Senden der E-Mail-Nachricht. Schließlich ruft es die E-Mail-Konfiguration aus der Konfiguration der Anwendung ab. Anschließend werden diese verwendet, um das „EmailSenderHandler“-Objekt zu initialisieren und zurückzugeben.

Aktualisieren Sie die Routing-Tabelle

Bei all diesen Änderungen muss noch eine letzte Änderung vorgenommen werden, bevor wir den Code testen und eine E-Mail senden können. Wir müssen die Routing-Tabelle aktualisieren, sodass die Standardroute unsere neue Handler-Klasse als Handler der Route anstelle von „HomePageHandler“ verwendet. Ersetzen Sie dazu die Definition der Standardroute in „config/routes.php“ durch das folgende Beispiel.

Senden Sie die erste E-Mail

Jetzt ist es an der Zeit, die erste E-Mail zu versenden. Starten Sie dazu zunächst die Anwendung, indem Sie den folgenden Befehl im Terminal ausführen.

Stellen Sie dann mit cURL eine GET-Anforderung an „ http://localhost:8080 “, wie im Beispiel unten, und ersetzen Sie die Werte in spitzen Klammern durch relevante Details für Ihre E-Mail.

Sie sollten die Ausgabe von „{“status“:202,“message“:““}“ an das Terminal sehen, und Sie sollten eine E-Mail erhalten, die wie das Bild unten aussieht.

Hinweis: Sie können stattdessen gerne Verwenden Sie Transaktions-E-Mail-Vorlagen anstelle von Vorlagenzeichenfolgen

Obwohl wir in der Lage waren, eine E-Mail mit sowohl einem Klartext- als auch einem HTML-Text zu senden, ist die Art und Weise, wie wir dies getan haben, jedoch alles andere als ideal. Für jede E-Mail, die wir senden – und unsere Anwendung kann am Ende ziemlich viele senden – müssen wir einen Klartext und einen HTML-Body für sie hinzufügen.

Aber das Speichern der E-Mail-Body-Definitionen im Code erfordert den Großteil der Arbeit vom Entwicklungsteam. Allerdings ist es, zumindest meiner Erfahrung nach, oft so, dass andere Teams, häufig Marketing-Teams, E-Mail-Vorlagen erstellen und pflegen.

Aus diesem Grund und weil es die Entwicklung beschleunigen und die Last auf mehrere Teams verteilen würde, werden wir die Anwendung so umgestalten, dass transaktionale E-Mail-Vorlagen verwendet werden . Sie können diese über die Twilio SendGrid-Benutzeroberfläche von Teammitgliedern erstellen und verwalten, die möglicherweise wenig oder keine technische Erfahrung haben, anstatt im Code.

Wenn Sie noch nichts davon gehört haben, werden sie im Twilio SendGrid-Glossar wie folgt definiert:

Transaktions-E-Mail-Vorlagen sind vorcodierte E-Mail-Layouts, die Vermarkter, Designer und Entwickler verwenden können, um schnell und einfach Transaktions-E-Mail-Kampagnen zu erstellen. Die Transaktions-E-Mail-Vorlagen von Twilio SendGrid ermöglichen sowohl technisch nicht versierten als auch technisch versierten Personen, Änderungen in Echtzeit an den E-Mails vorzunehmen, die ihre Empfänger erhalten.

Für diesen Artikel brauchen wir nur ein ziemlich einfaches. Befolgen Sie dazu die Details in der Twilio SendGrid-Dokumentation und erstellen Sie eine, deren Inhalt nur aus einem Einzeltextmodul besteht. Verwenden Sie dann für den Haupttext den folgenden Text.

Beachten Sie, dass die E-Mail 6 Ersetzungen enthält:

  • „first_name“: Der Vorname des Kunden
  • „last_name“: Der Nachname des Kunden
  • „sender_name“: Der Name des E-Commerce-Shops (The Little PHP Shop)
  • „sender_state“: Der Status des E-Commerce-Shops
  • „sender_country“: Das Land des E-Commerce-Shops
  • „support_email“: Die Support-E-Mail, die Kunden verwenden können, um After-Sales-Support zu erhalten

Daher müssen wir diese Informationen unserer Anwendung zur Verfügung stellen. Vor- und Nachname des Kunden liegen uns bereits vor. Die verbleibenden 4 Ersetzungen werden global sein, also fügen wir wie zuvor die Konfiguration unten zu „ config/autoload/mail.global.php “ nach dem „templates“-Element hinzu.

Ersetzen Sie mit der neu erstellten Konfigurationsdatei in der „handle“-Methode „EmailSenderHandler“ die beiden Aufrufe von „$this->mail->addContent()“ durch den folgenden Code.

Die 2 Methodenaufrufe fügen die Absenderdetails hinzu und unterstützen die E-Mail-Adresse als globale Ersetzungen. Diese Ersetzungen gelten vor allen anderen Ersetzungen für den E-Mail-Text, werden jedoch außer Kraft gesetzt, wenn es Ersetzungen mit demselben Schlüssel für einen E-Mail-Empfänger gibt.

Als Nächstes müssen Sie die ID der Transaktions-E-Mail-Vorlage abrufen. Sie finden es, indem Sie in der Vorlagenliste auf den Namen der Vorlage klicken , wie Sie im Screenshot unten sehen können.

Kopieren Sie es und speichern Sie es in „config/autoload/mail.global.php“ in einem neuen Element mit dem Schlüssel „template_id“ und entfernen Sie dann „plain“ und „HTML“. Wenn Sie fertig sind, sieht das Element „mail/templates“ des zurückgegebenen Arrays wie im folgenden Code aus, wobei „<the template's id>“ die ID Ihrer Vorlage ersetzt.

Nachdem die Konfiguration aktualisiert wurde, müssen wir nun einen Aufruf zur „Mail“ „setTemplateId“-Methode in der „EmailSenderHandler“ „handle“-Methode hinzufügen und die Vorlagen-ID übergeben, die wir gerade zu „config/autoload/mail.global“ hinzugefügt haben. php.“ Sie können ein Beispiel im folgenden Code sehen.

Lassen Sie uns die Änderungen testen

Stellen Sie wie zuvor mit cURL eine GET-Anfrage an „ http://localhost:8080 “, um zu testen, ob die Änderungen wie erwartet funktionieren. Sie sollten die Ausgabe „{“status“:202,“message“:““}“ an das Terminal sehen, wie im vorherigen Beispiel. In Ihrem E-Mail-Posteingang sollten Sie eine schöne E-Mail sehen, in der die Ersetzungen wie im folgenden Screenshot ersetzt sind.

Hängen Sie eine PDF-Rechnung an

Da wir nun dynamische Vorlagen verwenden, fügen wir die PDF-Rechnung an, über die wir oben im Artikel gesprochen haben. Um Ihnen die zeit- und mühsame Suche oder Erstellung einer Rechnung zu ersparen, habe ich eine Muster-PDF-Rechnung erstellt , die Sie für diesen Artikel verwenden können. Speichern Sie es im „ data“ -Verzeichnis der Anwendung .

Hinweis: Um eine Rechnung anzuhängen, müssen wir die Methode „Mail“ „addAttachment“ verwenden, die Sie im nächsten Codebeispiel sehen können. Die Methode akzeptiert 5 Argumente, aber wir liefern nur die ersten 4. Dies sind:

  1. Ein „ Attachment“ -Objekt oder eine Base64-codierte Zeichenfolge . Wenn der Wert dieses Parameters nicht base64-codiert ist, erledigt die Methode dies für uns.
  2. Der MIME-Typ des Anhangs (jetzt bekannt als Medientyp ).
  3. Der Dateiname des Anhangs . Dies ist der Name, unter dem die Datei standardmäßig gespeichert wird, es sei denn, der Benutzer ändert ihn.
  4. Die Inhaltsdisposition des Anhangs . Wenn Sie mit der Inhaltsdisposition nicht vertraut sind, bedeutet die Inline -Inhaltsdisposition, dass der Anhang automatisch angezeigt werden soll, wenn die Nachricht angezeigt wird, und die Inhaltsdisposition des Anhangs bedeutet, dass der Anhang nicht automatisch angezeigt wird und eine Aktion des Benutzers erfordert öffne es.

Im folgenden Codebeispiel liest die file_get_contents - Methode von PHP den Inhalt der Datei in eine neue Variable namens „$invoice“ ein. Anschließend wird das PDF an die Nachricht angehängt, indem die Methode „addAttachment“ aufgerufen wird.

Hier, wir:

  • Übergeben Sie den Inhalt der Rechnung, die Base64-codiert wird
  • Setzen Sie den MIME-Typ auf „application/pdf“, da wir eine PDF-Datei anhängen
  • Legen Sie den Dateinamen der Rechnung auf einen fiktiven Namen fest, den ein Kunde vernünftigerweise erwarten könnte
  • Stellen Sie die Inhaltsdisposition auf „Anhang“

Nachdem wir diese Änderungen abgeschlossen haben, testen wir, ob sie funktionieren. Führen Sie die gleiche cURL-Anfrage aus, die wir die letzten 2 Mal ausgeführt haben. Dann sollten Sie in Ihrem E-Mail-Posteingang eine schöne E-Mail mit der Beispiel-PDF-Rechnung sehen, die beim Anzeigen der E-Mail sichtbar ist.

So senden Sie E-Mails mit PHP mit Twilio SendGrid und Mezzio

Während wir beim Versenden von E-Mails mit Twilio SendGrid und Mezzio nur an der Oberfläche der Möglichkeiten gekratzt haben, können Sie jetzt eine E-Mail mit Klartext und HTML-Text sowie mit Anhang senden. Sie haben auch gelernt, wie Sie Transaktionsvorlagen und Substitutionen verwenden, die Sie global und auf Empfängerbasis festlegen können.

Ich empfehle Ihnen dringend, einen Blick in die Dokumentation der PHP-Bibliothek zu werfen, um zu sehen, was sonst noch verfügbar ist, wie das Planen von E-Mail-Versendungen, das Anhängen einer Datei von Amazon S3, das Hinzufügen von Kopfzeilen und das Hinzufügen von Abschnitten und Kategorien.

Matthew Setter ist PHP-Editor im Twilio Voices-Team und – natürlich – PHP-Entwickler. Er ist auch der Autor von Mezzio Essentials . Wenn er keinen PHP-Code schreibt, bearbeitet er hier bei Twilio großartige PHP-Artikel. Erreichbar ist er über:

  • E- Mail: matthew@matthewsetter.com
  • Internet: http://matthewsetter.com
  • Twitter: @settermjd
  • GitHub: https://github.com/settermjd