Applet de lista de e-mails de código aberto usando o SDK para PHP do Mailgun

Esta publicação foi escrita por Jeff Reifman, um consultor de tecnologia  sediado em Seattle e fundador do Geogram, um serviço de e-mail em grupo gratuito para locais, desenvolvido pelo Mailgun. Siga-o em @reifman.

Embora o Mailgun seja conhecido principalmente como um mecanismo de e-mail escalável baseado na nuvem, sua funcionalidade de lista de e-mails oferece uma maneira fácil e conveniente de gerenciar listas e enviar mensagens de transmissão em massa para vários destinatários. Você pode enviar mensagens para as listas de e-mails do Mailgun usando seu provedor de e-mail da Web favorito, cliente de e-mail, smartphone ou pela API. Além disso, o Mailgun fornece APIs para gerenciar e fazer envios para as suas listas de forma programática. Recentemente, o Mailgun lançou um novo SDK para PHP para facilitar ainda mais o uso de sua API.

As listas de e-mails do Mailgun podem fornecer a funcionalidade principal de que você precisa para deixar de usar serviços de e-mail pagos ou aplicativos de lista de código aberto, como o PHPList. Eu uso os serviços de lista do Mailgun para me comunicar com minha rede de contatos, interagir com minhas comunidades sociais e para alcance comercial.

Este tutorial não apenas descreve como usar a API de listas de e-mails do Mailgun para gerenciar suas próprias listas usando PHP, mas também fornece o código-fonte instalável, de código aberto e gratuito para um pequeno aplicativo baseado na Web, o ListApp, que permite gerenciar e enviar e-mails por meio da API de listas usando o Mailgun.com. O objetivo principal é demonstrar como você pode usar a API de listas do Mailgun no seu aplicativo. O ListApp foi escrito no Yii Framework para PHP. Você não precisa saber nada sobre o Yii Framework para executar o aplicativo.

O aplicativo fornece um front-end simples baseado na Web para cenários comuns que você pode usar com os recursos de lista de e-mails do Mailgun:

• Sincronização das suas listas e membros da lista
• Criação, atualização e exclusão de listas
• Importação de membros para uma lista
• Envio de mensagens para listas
• Disponibilização de um formulário de assinatura público com

O código do ListApp está disponível gratuitamente no Github.com. Você pode instalá-lo em qualquer servidor PHP/MySQL. Incluí instruções para configurar o ListApp em um servidor Rackspace Cloud Ubuntu 12.04 com 1 GB de RAM. Usamos Ubuntu Linux, Apache, PHP 5.x, MySQL 5.x, PEAR e bibliotecas cURL.

Mesmo que você use seu próprio servidor, você deve ler as instruções de configuração do Rackspace para criar um site Apache, criar e instalar o banco de dados e gerar as suas credenciais de login. Também é importante personalizar as configurações do seu site no arquivo config-listapp.ini.

Você precisará criar uma conta gratuita (ou de nível superior) do Mailgun para obter suas chaves de API para o arquivo de configurações.

Se você tiver uma conta paga, precisará adicionar seus domínios e criar configurações de DNS para usá-los. Se você usar uma conta gratuita, o seu domínio será suaescolha.mailgun.org. Portanto, os endereços da sua lista podem ser curinga@suaescolha.mailgun.org. As suas chaves de API do Mailgun serão exibidas na página inicial do painel de controle.

O uso da API de listas de e-mails do Mailgun é muito simples. O Mailgun fornece a sua própria documentação da API de listas de e-mails para nos ajudar. Você pode revisar como o ListApp usa a API do Mailgun no nosso componente Yiigun.php. O ListApp usa o SDK para PHP do Mailgun para interagir com o Mailgun.

Aqui estão alguns exemplos de usos comuns da API de listas de e-mails com o Mailgun:

Sempre que a classe Yiigun é usada, o construtor é chamado, criando uma inicialização segura com a API do Mailgun:

                                

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

                                
                            

Depois de fazer login no ListApp, clique na opção “Sincronizar”. Isso buscará cópias de todas as listas de e-mails existentes no Mailgun e vai baixar todos os membros para o banco de dados local. Isso basicamente sincroniza a sua lista de e-mails a partir do site Mailgun.com. Esta opção não sincroniza os dados locais de volta para o servidor.

Esta é a função fetchLists. O uso do SDK para PHP do Mailgun torna isso muito simples:

                                

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

                                
                            

Veja como buscamos os membros:

                                

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

                                
                            

Você pode criar novas listas de e-mails usando as opções do menu à direita do ListApp. Cada lista exige um nome, um endereço de e-mail da lista e uma descrição. Quando você cria uma nova lista, o ListApp também faz o upload da lista e de suas configurações para o Mailgun.com. Você também pode atualizar as propriedades de qualquer lista.

Veja como criamos uma nova lista:

                                

                                    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;
}

                                
                            

Veja como atualizamos as propriedades da lista de e-mails:

                                

                                    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;
}

                                
                            

Você pode importar novos membros para qualquer lista a partir do ListApp. Usamos as bibliotecas de análise de lista de e-mails do PEAR para este recurso. Você pode colar qualquer lista de endereços de e-mail no formato Nome Pessoal separados por vírgulas ou quebras de linha. O ListApp adicionará os membros localmente e fará o upload deles para o Mailgun.com.

Para adicionar membros em massa, primeiro, criamos uma string JSON dos novos membros para upload… Aqui está um exemplo de código que você pode usar. Você pode conferir um exemplo completo aqui.

                                

                                    $json_upload = '[';

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

$json_upload .= ']';

                                
                            

Em seguida, chamamos a função de upload em massa com essa string JSON:

                                

                                    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;
}

                                
                            

Você também pode adicionar membros individuais às listas usando a opção de menu “Adicionar um membro”.

Você pode enviar uma mensagem para qualquer lista usando o menu à direita. Entregamos a mensagem de saída ao Mailgun como qualquer outra mensagem:

                                

                                    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;
}

                                
                            

O Mailgun gerenciará então a entrega da mensagem aos destinatários individuais.

Você também pode usar algumas das variáveis de destinatário genéricas do Mailgun para incluir saudações pessoais, como Oi, %recipient_fname% (confira as variáveis de modelo).

Você pode ver o formulário de assinatura na página de detalhes da lista do ListApp. E você pode direcionar os usuários para o formulário de assinatura público de uma lista em https://listapp.yourdomain.com/request/create/<list-id#&gt;:

O ListApp também faz uso da nova API de validação de e-mail do Mailgun que detecta erros de digitação como @gmal.com:

Estamos usando a validação AJAX integrada do Yii para integrar a API de validação de e-mail do Mailgun. A função de regra do Yii chama um validador personalizado que criamos, que se comunica com o Mailgun Validator – confira o modelo de solicitação:

                                

                                    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;
}

                                
                            

Quando uma solicitação de assinatura é validada, usamos o Mailgun SDK Opt In Handler para enviar um e-mail ao usuário com um link de verificação, o que evita adições falsas:

                                

                                    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']
    );
}

                                
                            

Veja como adicionamos membros assinantes quando eles clicam no link de verificação – no 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;
}

                                
                            

O Yii é essencialmente uma estrutura MVC como o Ruby on Rails, mas com toda a simplicidade e maturidade do PHP. É rápido, eficiente e relativamente simples. Ele também inclui suporte a scaffolding e geração de código, active record, suporte a transações, localização I18n, suporte a armazenamento em cache, entre outros. A documentação, o suporte da comunidade e os plug-ins disponíveis também são muito bons. Foram necessárias menos de 10 horas usando o Yii para compilar o ListApp.

Contudo, se você preferir não usar o Yii, poderá usar como base o componente Yiigun utilizado no ListApp. O Yiigun.php é essencialmente um arquivo de classe do PHP com métodos e auxiliares para aproveitar o SDK de listas de e-mails do Mailgun.

A versão atual do ListApp se comunica com blog.mailgun.com/post/the-php-sdk-the-first-of-many-official-mailgun-sdks/Mailgun em tempo real e não possui um tratamento de erros extensivo. A longo prazo, seria bom adicionar solicitações de API assíncronas em fila.

Além do próprio material do Mailgun documentação da API de listas de e-mails (que inclui exemplos em cURL, Ruby, PHP, Python, Java e C#), você pode revisar, extrair e adaptar o arquivo Yiigun.php e as suas funções para o seu próprio aplicativo ou estrutura em PHP.

Se não usar o Yii, você precisará usar o Composer para instalar o SDK de acordo com as instruções de instalação do Mailgun.

Se você quiser adicionar recursos ou estender o ListApp para seus próprios fins, sugiro que você faça um fork do código no Github. Se lançarmos atualizações ou novos recursos, você poderá mesclar as alterações no seu trabalho a qualquer momento.

Se você quiser contribuir com o ListApp adicionando recursos e nos pedindo para incluí-los na base de código principal (adoraríamos isso!), você pode enviar um pull request.

Git é uma ferramenta colaborativa de gerenciamento de código-fonte baseada na Internet extremamente poderosa, mas pode ser um pouco confusa para quem está começando. Confira a página de ajuda para acessar os guias de usos comuns.

• ListApp: aplicativo de lista de e-mails de código aberto baseado em Yii no Github
• Do ListApp: Instruções de instalação na RackSpace Cloud
• ListApp arquivo Yiigun.php para extração com outros aplicativos baseados em PHP
• Relatar problemas com o ListApp
• Como o Geogram criou um serviço de e-mail em grupo gratuito usando o Yii para PHP com MySQL
• Yii Framework
• Sobre 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!