Product
O SDK do PHP: o primeiro de muitos SDKs oficiais do Mailgun
Hoje, temos a alegria de anunciar que, para quem desenvolve em PHP, ficou ainda mais fácil enviar mensagens com o Mailgun! Nas últimas semanas, estivemos trabalhando bastante na criação de SDKs para a API do Mailgun. O SDK permite que você interaja facilmente com a nossa API, removendo todo o código boilerplate necessário para interagir com um serviço da web HTTP. Hoje, estamos lançando a versão para PHP do SDK. Outras linguagens estarão disponíveis em breve.
Para quem não tem familiaridade com um SDK, vamos primeiro revisar o que é necessário para enviar uma mensagem usando a biblioteca HTTP padrão CURL para PHP.
Enviando uma mensagem com CURL:
function send_simple_message() {
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, 'api:key-example');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_URL,
'https://api.mailgun.net/v2/samples.mailgun.org/messages');
curl_setopt($ch, CURLOPT_POSTFIELDS,
array('from' => 'Dwight Schrute ',
'to' => 'Michael Scott ',
'subject' => 'The Printer Caught Fire',
'text' => 'We have a problem.'));
$result = curl_exec($ch);
curl_close($ch);
return $result;
}
echo send_simple_message();
O código acima enviará uma mensagem usando a API do Mailgun, no entanto, há muito código ali que, embora importante, é complexo e, a menos que você seja especialista em CURL, pode ser um pouco confuso.
Com nosso novo SDK, conseguimos reduzir a quantidade de código necessária para apenas algumas linhas.
Enviando uma mensagem com o SDK do PHP do Mailgun:
# First, instantiate the SDK with your API credentials and define your domain.
$mgClient = new Mailgun("key-example");
$domain = "example.com";
# Now, compose and send your message.
$mgClient->sendMessage($domain,
array('from' => 'Dwight Schrute ',
'to' => 'Michael Scott ',
'subject' => 'The Printer Caught Fire',
'text' => 'We have a problem.'));
Obtendo logs com o SDK do PHP do Mailgun:
# First, instantiate the SDK with your API credentials and
define your domain.
$mgClient = new Mailgun('key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
$domain = 'samples.mailgun.org';
# Now, issue a get against the "log" resource URL.
$result = $mgClient->get("$domain/log", array('limit' => 5, 'skip' => 0));
Todas as ações HTTP retornam um objeto de resposta com o qual você pode interagir facilmente.
# Obtain the HTTP response code. (e.g. 200)
$responseCode = $result->http_response_code;
# Obtain the total count of results provided by the query.
$responseBody = $result->http_response_body->total_count;
# Iterate through the results and echo the message IDs.
$logItems = $result->http_response_body->items;
for($logItems as $logItem){
echo $logItem->message_id . "n";
}
Se quiser começar a usar o SDK hoje mesmo, o código está disponível como um repositório público no GitHub (mailgun-php). Você encontrará formas de fazer tudo o que é possível com a API do Mailgun. Para exemplos de uso adicionais, confira o arquivo README no repositório. Mas não paramos por aí… Criamos alguns utilitários dentro do SDK.
Message Builder
A criação de uma matriz de parâmetros pode ser difícil para algumas implementações de código, por isso incluímos uma classe que permite fazer chamadas de método que constroem automaticamente uma matriz de parâmetros de mensagem formatada corretamente.
Enviando uma mensagem com o SDK do PHP do Mailgun + Message Builder:
# First, instantiate the SDK with your API credentials and define
your domain.
$mgClient = new Mailgun("key-example");
$domain = "example.com";
# Next, instantiate a Message Builder object from the SDK.
$msgBldr = $mgClient->MessageBuilder();
# Define the from address.
$msgBldr->setFromAddress("dwight@example.com",
array("first"=>"Dwight", "last" => "Schrute"));
# Define a to recipient.
$msgBldr->addToRecipient("michael@example.com",
array("first" => "Michael", "last" => "Scott"));
# Define a cc recipient.
$msgBldr->addCcRecipient("pam@example.com",
array("first" => "Pam", "last" => "Beesly"));
# Define the subject.
$msgBldr->setSubject("Help!");
# Define the body of the message.
$msgBldr->setTextBody("The printer is on fire.");
# Other Optional Parameters.
$msgBldr->addCampaignId("Sabre-Printer-Fire");
$msgBldr->addCustomHeader("Customer-Id", "12345");
$msgBldr->addAttachment("@/sabre.jpg");
$msgBldr->setDeliveryTime("tomorrow 8:00AM", "PST");
# Finally, send the message.
$mgClient->post('{$domain}/messages', $msgBldr->getMessage());
Para conferir uma lista de todas as funções disponíveis, acesse a lista no Github.
Batch Message
Além do Message Builder, temos o Batch Message. Essa classe permite compilar uma mensagem e enviar uma mensagem de modelo em lotes para até 1.000 destinatários por postagem. O benefício de usar essa classe é que a contagem de destinatários é monitorada e a mensagem é enviada automaticamente para o endpoint quando você adiciona o milésimo destinatário. Isso significa que você pode compilar sua mensagem e começar a iterar em seu banco de dados. Não se preocupe em enviar a mensagem, pois o SDK se encarregará de fazer a postagem na API quando necessário.
Enviando uma mensagem com o SDK do PHP do Mailgun + Batch Message:
# First, instantiate the SDK with your API credentials and define
your domain.
$mgClient = new Mailgun("key-example");
$domain = "example.com";
# Next, instantiate a Message Builder object from the SDK, pass in your
sending domain.
$batchMsg = $mgClient->BatchMessage($domain);
# Define the from address.
$batchMsg->setFromAddress("dwight@example.com",
array("first"=>"Dwight", "last" => "Schrute"));
# Define the subject.
$batchMsg->setSubject("Help!");
# Define the body of the message.
$batchMsg->setTextBody("The printer is on fire!");
# Next, let's add a few recipients to the batch job.
$batchMsg->addToRecipient("pam@example.com",
array("first" => "pam", "last" => "Beesly"));
$batchMsg->addToRecipient("jim@example.com",
array("first" => "Jim", "last" => "Halpert"));
$batchMsg->addToRecipient("andy@example.com",
array("first" => "Andy", "last" => "Bernard"));
...etc...etc...
// After 1,000 recipeints, Batch Message will automatically post your message
to the messages endpoint.
// Call finalize() to send any remaining recipients still in the buffer.
$batchMsg->finalize();
Como é possível ver, o Batch Message na verdade é uma extensão do Message Builder. Todas as funções disponíveis no Message Builder também estão disponíveis no Batch Message. Confira a documentação completa no Github.
Opt-In Handler
Por fim, criamos um manipulador de duplo opt-in simples para ajudar você a gerar links de opt-in exclusivos. O manipulador de opt-in também usa nosso serviço gratuito de validação de endereços para validar a precisão dos endereços de e-mail.
O fluxo típico de uso desta classe seria o seguinte:
Destinatário solicita cadastro -> [Validar endereço do destinatário] -> [Gerar link de opt-in] -> [Enviar link de opt-in por e-mail ao destinatário]
Destinatário clica no link de opt-in -> [Validar link de opt-in] -> [Cadastrar usuário] -> [Enviar confirmação final]
O ideal é usar essa classe para os formulários de assinatura do seu site, portanto você precisará de um servidor web acessível pela internet para lidar com o clique no link de validação.
Deixe-nos saber o que você acha. Há algo mais que você gostaria de ver no SDK? Ou algo de que você gosta muito. Agradecemos o seu feedback!
Bons envios,
Os Mailgunners
