Open-Source-Mailinglisten-Applet mit dem Mailgun-PHP-SDK

Dieser Beitrag wurde von Jeff Reifman verfasst, einem in Seattle ansässigen Technologieberater und Gründer von Geogram, einem kostenlosen Gruppen-E-Mail-Service für lokale Orte, der von Mailgun betrieben wird. Folgen Sie ihm unter @reifman.

Während Mailgun in erster Linie als skalierbare cloudbasierte E-Mail-Engine bekannt ist, bietet die Mailinglisten-Funktion eine einfache und bequeme Möglichkeit, Listen zu verwalten und Broadcast-Nachrichten an ein breites Publikum zu senden. Senden Sie Nachrichten an die Mailinglisten von Mailgun über Ihren bevorzugten Web-E-Mail-Anbieter, Ihren E-Mail-Client, Ihr Smartphone oder über die API. Zudem bietet Mailgun APIs zur programmgesteuerten Verwaltung und zum Versand an Ihre Listen. Kürzlich hat Mailgun ein neues SDK für PHP herausgebracht, das die Nutzung der API noch einfacher gestaltet.

Die Mailinglisten von Mailgun bieten genau die Kernfunktionen, die Sie benötigen, um von kostenpflichtigen E-Mail-Services oder Open-Source-Listenanwendungen wie PHPList zu wechseln. Ich nutze die Listenservices von Mailgun, um mit meinem Freundeskreis zu kommunizieren, meine sozialen Communitys zu erreichen und für geschäftliche Kontakte.

Dieses Tutorial beschreibt nicht nur, wie Sie die Mailinglisten-API von Mailgun nutzen, um Ihre eigenen Listen über PHP zu verwalten, sondern stellt auch kostenlosen, quelloffenen und installierbaren Quellcode für eine kleine webbasierte Anwendung bereit: ListApp. Damit verwalten und versenden Sie E-Mails über die Listen-API von Mailgun.com. Die App soll in erster Linie demonstrieren, wie Sie die Listen-API von Mailgun in Ihrer Anwendung einsetzen. ListApp basiert auf dem Yii-Framework für PHP. Sie benötigen keine Kenntnisse des Yii-Frameworks, um die Anwendung auszuführen.

Die Anwendung bietet ein einfaches webbasiertes Front-End für gängige Szenarien im Zusammenhang mit den Mailinglisten-Funktionen von Mailgun:

• Synchronisierung Ihrer Listen und Listenmitglieder
• Erstellen, Aktualisieren und Löschen von Listen
• Importieren von Mitgliedern in eine Liste
• Senden von Nachrichten an Listen
• Bereitstellung eines öffentlichen Abonnement-Formulars mit

Der Code für ListApp ist frei verfügbar auf Github.com. Installieren Sie die App auf einem beliebigen PHP/MySQL-Server. Ich habe eine Anleitung für die Einrichtung von ListApp auf einem Rackspace-Cloud-Ubuntu-12.04-Server mit 1 GB RAM beigefügt. Wir verwenden Ubuntu Linux, Apache, PHP 5.x, MySQL 5.x sowie PEAR- und cURL-Bibliotheken.

Selbst wenn Sie einen eigenen Server nutzen, sollten Sie die Einrichtungsanleitung von Rackspace lesen , um eine Apache-Website zu erstellen, die Datenbank zu installieren und Ihre Anmeldedaten zu generieren. Es ist auch wichtig, Ihre Website-Einstellungen in der Datei config-listapp.ini anzupassen.

Melden Sie sich für ein kostenloses (oder höherwertiges) Mailgun-Konto an, um Ihre API-Schlüssel für die Einstellungsdatei zu erhalten.

Wenn Sie ein kostenpflichtiges Konto haben, fügen Sie Ihre Domains hinzu und erstellen Sie die entsprechenden DNS-Einstellungen. Bei einem kostenlosen Konto lautet Ihre Domain yourchoice.mailgun.org. Daher können Ihre Listenadressen wildcard@yourchoice.mailgun.org lauten. Ihre Mailgun-API-Schlüssel finden Sie auf der Startseite des Control-Panels.

Die Nutzung der Mailinglisten-API von Mailgun ist unkompliziert. Mailgun stellt eine eigene Mailinglisten-API-Dokumentation zur Unterstützung bereit. Wie ListApp die Mailgun-API nutzt, sehen Sie in der Komponente Yiigun.php. ListApp nutzt das Mailgun-PHP-SDK für die Interaktion mit Mailgun.

Hier sind einige Beispiele für die gängige Nutzung der Mailinglisten-API mit Mailgun:

Wann immer die Yiigun-Klasse verwendet wird, wird der Konstruktor aufgerufen, was eine sichere Verbindung zur API von Mailgun herstellt:

                                

                                    function __construct()
{
    // Initialize Mailgun connection
    $this->mg = new Mailgun(Yii::app()->params['mailgun']['api_key']);
}

                                
                            

Sobald Sie bei ListApp angemeldet sind, klicken Sie auf die Option „Synchronisieren“. Dadurch werden Kopien aller bestehenden Mailinglisten bei Mailgun abgerufen und alle ihre Mitglieder in die lokale Datenbank heruntergeladen. Im Wesentlichen wird Ihre Mailingliste von der Website Mailgun.com heruntergeladen und synchronisiert. Diese Option synchronisiert nicht in die andere Richtung (Upload).

Hier ist die Funktion „fetchLists“. Mit dem Mailgun-PHP-SDK ist dies ganz einfach:

                                

                                    public function fetchLists()
{
    $result = $this->mg->get("lists");
    return $result->http_response_body;
}

                                
                            

So rufen wir Mitglieder ab:

                                

                                    public function fetchListMembers($address)
{
    $result = $this->mg->get("lists/" . $address . '/members');
    return $result->http_response_body;
}

                                
                            

Erstellen Sie neue Mailinglisten über die Menüoptionen auf der rechten Seite der ListApp. Jede Liste benötigt einen Namen, eine E-Mail-Adresse und eine Beschreibung. Wenn Sie eine neue Liste erstellen, lädt ListApp die Liste sowie ihre Einstellungen auch auf Mailgun.com hoch. Aktualisieren Sie zudem die Eigenschaften einer beliebigen Liste.

So erstellen wir eine neue Liste:

                                

                                    public function listCreate($newlist)
{
    $result = $this->mg->post("lists", [
        'address'      => $newlist->address,
        'name'         => $newlist->name,
        'description'  => $newlist->description,
        'access_level' => $newlist->access_level
    ]);

    return $result->http_response_body;
}

                                
                            

So aktualisieren wir die Eigenschaften einer Mailingliste:

                                

                                    public function listUpdate($existing_address, $model)
{
    $result = $this->mg->put("lists/" . $existing_address, [
        'address'      => $model->address,
        'name'         => $model->name,
        'description'  => $model->description,
        'access_level' => $model->access_level
    ]);

    return $result->http_response_body;
}

                                
                            

Importieren Sie neue Mitglieder aus ListApp in eine beliebige Liste. Für diese Funktion verwenden wir die E-Mail-Listen-Parsing-Bibliotheken von PEAR. Fügen Sie eine beliebige Liste von E-Mail-Adressen im Format Personal Name ein, getrennt durch Kommas oder Zeilenumbrüche. ListApp fügt die Mitglieder lokal hinzu und lädt sie auf Mailgun.com hoch.

Um Mitglieder in großen Mengen hinzuzufügen, erstellen wir zunächst einen JSON-String der hochzuladenden neuen Mitglieder … hier ist ein passender Beispielcode. Ein vollständiges Beispiel finden Sie hier.

                                

                                    $json_upload = '[';

foreach ($addresses as $i) {
    $json_upload .= '{';
    $json_upload .= '"name": "' . $i->name . '", ';
    $json_upload .= '"address": "' . $i->address . '"';
    $json_upload .= '},';
}

$json_upload .= ']';

                                
                            

Anschließend rufen wir die Bulk-Upload-Funktion mit diesem JSON-String auf:

                                

                                    public function memberBulkAdd($list = '', $json_str = '')
{
    $result = $this->mg->post("lists/" . $list . '/members.json', [
        'members'    => $json_str,
        'subscribed' => true,
        'upsert'     => 'yes'
    ]);

    return $result->http_response_body;
}

                                
                            

Über die Menüoption „Mitglied hinzufügen“ nehmen Sie auch einzelne Mitglieder in Listen auf.

Senden Sie über das rechte Menü eine Nachricht an eine beliebige Liste. Wir übergeben die ausgehende Nachricht wie jede andere Nachricht an Mailgun:

                                

                                    public function send_simple_message($to = '', $subject = '', $body = '', $from = '')
{
    if ($from '') {
        $from = Yii::app()->params['supportEmail'];
    }

    $domain = Yii::app()->params['mail_domain'];

    $result = $this->mg->sendMessage($domain, [
        'from'    => $from,
        'to'      => $to,
        'subject' => $subject,
        'text'    => $body,
    ]);

    return $result->http_response_body;
}

                                
                            

Mailgun übernimmt dann die Zustellung der Nachricht an die Empfangenden.

Nutzen Sie auch einige der allgemeinen Mailgun-Empfängervariablen, um persönliche Anreden einzufügen, z. B. Hallo %recipient_fname% (siehe Vorlagenvariablen).

Sehen Sie sich das Abonnement-Formular auf der Detailseite der ListApp-Liste an. Verweisen Sie Ihre Zielgruppe außerdem unter folgendem Link auf das öffentliche Abonnement-Formular einer Liste: https://listapp.yourdomain.com/request/create/<list-id#&gt;:

ListApp verwendet zudem die neue E-Mail-Validierungs-API von Mailgun , die Tippfehler wie @gmal.com erkennt:

Wir verwenden die integrierte AJAX-Validierung von Yii, um die E-Mail-Validierungs-API von Mailgun zu integrieren. Die Regelfunktion von Yii ruft einen von uns entwickelten benutzerdefinierten Validator auf, der mit dem Mailgun-Validator kommuniziert – siehe Request-Modell:

                                

                                    public function rules()
{
    return array(
        array('address', 'required'),
        array('name, address', 'length', 'max' => 255),
        array('address', 'mailgunValidator'),
    );
}

public function mailgunValidator($attribute, $params)
{
    $yg = new Yiigun();
    $result = $yg->validate($this->$attribute);

    if ($result->is_valid) {
        return false;
    } else {
        $this->addError(
            $attribute,
            'There is a problem with your email address ' . $result->address .
            '. Did you mean ' . $result->did_you_mean . '?'
        );
    }
}

function validate($email = '')
{
    $this->mgValidate = new Mailgun(Yii::app()->params['mailgun']['public_key']);
    $result = $this->mgValidate->get('address/validate', array('address' => $email));
    return $result->http_response_body;
}

                                
                            

Sobald eine Abonnement-Anfrage validiert ist, verwenden wir den Mailgun SDK Opt In Handler, um der anfragenden Person eine E-Mail mit einem Verifizierungslink zu senden; dies verhindert fehlerhafte Einträge:

                                

                                    public function generateVerifyHash($model, $mglist)
{
    // Generate secure hash for verifying subscription requests
    $verify_secret = Yii::app()->params['verify_secret'];
    $optInHandler = $this->mg->OptInHandler();
    $generatedHash = $optInHandler->generateHash(
        $mglist->address,
        $verify_secret,
        $model->address
    );

    // Remove encodings - fixes Yii routing issue
    $generatedHash = str_ireplace('%', '', $generatedHash);

    return $generatedHash;
}

public function sendVerificationRequest($model, $mglist)
{
    // Send an email with the verification link
    $body = "Please verify your subscription by clicking on the link below:rn"
          . Yii::app()->getBaseUrl(true)
          . "/request/verify/"
          . $model->id
          . "/"
          . $model->hash;

    $this->send_simple_message(
        $model->address,
        'Please verify your subscription to ' . $mglist->name,
        $body,
        Yii::app()->params['support_email']
    );
}

                                
                            

So fügen wir abonnierte Kontakte hinzu, wenn diese auf den Verifizierungslink klicken – im RequestController:

                                

                                    public function actionVerify($id, $hash)
{
    $request = $this->loadModel($id);

    if ($hash $request->hash) {  // findByPk($request->mglist_id);

        // Insert new Member
        $member_id = $request->insertMember($request->name, $request->address);

        // Add member to this list
        Member::model()->addToList($member_id, $request->mglist_id);

        // Add member at Mailgun
        $yg = new Yiigun();
        $yg->memberAdd($mglist->address, $request->address, $request->name);

        $this->render('verify', array(
            'model'  => $this->loadModel($id),
            'mglist' => $mglist,
        ));
    } else {
        echo 'Sorry, your request is invalid.';
        yexit();
    }
}

public function memberAdd($list = '', $email = '', $name = '')
{
    $result = $this->mg->post(
        "lists/" . $list . '/members',
        array(
            'address'    => $email,
            'name'       => $name,
            'subscribed' => true,
            'upsert'     => 'yes'
        )
    );

    return $result->http_response_body;
}

                                
                            

Yii ist im Wesentlichen ein MVC-Framework wie Ruby on Rails, jedoch mit der gesamten Einfachheit und Ausgereiftheit von PHP. Es ist schnell, effizient und relativ unkompliziert. Es umfasst auch Scaffolding/Code-Generierung, Active Record, Transaktionsunterstützung, I18n-Lokalisierung, Caching-Support und vieles mehr. Die Dokumentation, der Community-Support und die verfügbaren Plugins sind ebenfalls hervorragend. Der Aufbau von ListApp mit Yii dauerte weniger als zehn Stunden.

Wenn Sie Yii jedoch nicht verwenden möchten, bauen Sie auf der in ListApp genutzten Yiigun-Komponente auf. Yiigun.php ist im Grunde eine PHP-Klassendatei mit Methoden und Hilfsfunktionen zur Nutzung des Mailgun-Mailinglisten-SDK.

Die aktuelle Version von ListApp kommuniziert in Echtzeit mit blog.mailgun.com/post/the-php-sdk-the-first-of-many-official-mailgun-sdks/Mailgun und verfügt über keine umfassende Fehlerbehandlung. Auf längere Sicht wäre es sinnvoll, asynchrone API-Anfragen in der Warteschlange hinzuzufügen.

Zusätzlich zu Mailguns eigener Mailinglisten-API-Dokumentation (die Beispiele in cURL, Ruby, PHP, Python, Java und C# enthält), prüfen, extrahieren und adaptieren Sie die Yiigun.php-Datei sowie deren Funktionen für Ihre eigene PHP-Anwendung oder Ihr eigenes Framework.

Wenn Sie Yii nicht verwenden, installieren Sie das SDK mit Composer gemäß der Installationsanleitung von Mailgun.

Wenn Sie Funktionen hinzufügen oder ListApp für Ihre eigenen Zwecke erweitern möchten, empfehle ich, dass Sie den Code auf Github forken. Wenn wir Updates oder neue Funktionen veröffentlichen, integrieren Sie die Änderungen jederzeit in Ihre Arbeit.

Wenn Sie zu ListApp beitragen möchten, indem Sie Funktionen hinzufügen und uns bitten, diese in die Hauptcodebasis aufzunehmen (darüber würden wir uns sehr freuen), reichen Sie gerne einen Pull-Request ein.

Git ist ein äußerst leistungsstarkes, internetbasiertes und kollaboratives Tool zur Quellcode-Verwaltung – der Einstieg kann jedoch etwas verwirrend sein. Werfen Sie einen Blick auf die Hilfeseite für Anleitungen zu gängigen Anwendungen.

• ListApp: Open-Source-Yii-basierte Mailinglisten-Anwendung auf Github
• ListApps Installationsanleitung für die RackSpace Cloud
• ListApp Yiigun.php-Datei zur Extraktion mit anderen PHP-basierten Anwendungen
• Probleme mit ListApp melden
• Wie Geogram einen kostenlosen Gruppen-E-Mail-Service mit Yii für PHP und MySQL aufbaute
• Yii-Framework
• Über Jeff ReifmanNewsCloud Consulting

Autor: The Sinch Mailgun team The Sinch Mailgun team shares news, best practices, and strategies to take your products and apps to the next level using email. Subscribe to our newsletter to get all the articles in your inbox!