Product
A gem oficial do Mailgun para Ruby chegou
Hoje, temos a alegria de anunciar que adicionamos o Ruby à lista de SDKs oficiais do Mailgun. Assim como em nosso SDK para PHP, incluímos alguns utilitários, como Message Builder, Batch Sending e Opt-in Handler, para simplificar tarefas comuns de desenvolvimento. Esperamos colaborar com a comunidade Ruby para tornar o SDK ainda melhor com o tempo. Você pode acessar o SDK no Github.
Para quem não tem familiaridade com um SDK, vamos primeiro revisar o que é necessário para enviar uma mensagem usando a biblioteca HTTPS padrão do Ruby.
Hoje, temos a alegria de anunciar que adicionamos o Ruby à lista de SDKs oficiais do Mailgun. Assim como em nosso SDK para PHP, incluímos alguns utilitários, como Message Builder, Batch Sending e Opt-in Handler, para simplificar tarefas comuns de desenvolvimento. Esperamos colaborar com a comunidade Ruby para tornar o SDK ainda melhor com o tempo. Você pode acessar o SDK no Github.
Para quem não tem familiaridade com um SDK, vamos primeiro revisar o que é necessário para enviar uma mensagem usando a biblioteca HTTPS padrão do Ruby.
Enviando uma mensagem:
require "net/https"
require "uri"
uri = URI.parse("https://api.mailgun.net/v2/samples.mailgun.org/messages")
data = {'to' => 'joe.sample@example.com',
'from' => 'bill.sample@example.com',
'subject' => 'Hello from Ruby!',
'text' => 'Sent via Mailgun.'}
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.request_uri)
request.basic_auth("api", "key-3ax6xnjp29jd6fds4gc373sgvjxteol0")
request.set_form_data(data)
response = http.request(request)
O exemplo acima enviará uma mensagem usando a API do Mailgun. No entanto, há muito código ali que, embora importante, é complicado e um tanto 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 Mailgun para Ruby:
require 'mailgun'
# First, instantiate the Mailgun Client with your API key
mg_client = Mailgun::Client.new "your-api-key"
# Define your message parameters
message_params = {:from => 'bob@sending_domain.com',
:to => 'sally@example.com',
:subject => 'The Ruby SDK is awesome!',
:text => 'It is really easy to send a message!'}
# Send your message through the client
mg_client.send_message "sending_domain.com", message_params
Obtendo eventos com o SDK do Mailgun para Ruby:
# First, instantiate the Client, then instantiate the Events helper.
mg_client = Mailgun::Client.new("your-api-key")
mg_events = Mailgun::Events.new(mg_client, "your-domain")
result = mg_events.get({'limit' => 25,
'recipient' => 'joe@example.com'})
result.to_h['items'].each do | item |
# outputs "Delivered - 20140509184016.12571.48844@example.com"
puts "#{item['event']} - #{item['message']['headers']['message-id']}"
end
Todas as ações HTTP retornam um objeto de resposta, que pode ser convertido em um hash ou YAML.
Digamos que queremos obter os próximos 25 resultados usando a mesma consulta. Basta emitir “next” no objeto “mg_events”. O SDK acompanha os links de paginação da Events API.
result = mg_events.next
Aviso: se o conjunto de resultados for menor que o seu limite, não se preocupe. Uma consulta subsequente de “next” retornará os próximos 25 resultados desde a última vez que você chamou “next” ou “get”.
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 Mailgun para Ruby + Message Builder:
# First, instantiate the Mailgun Client with your API key
mg_client = Mailgun::Client.new("your-api-key")
mb_obj = Mailgun::MessageBuilder.new()
# Define the from address
mb_obj.set_from_address("me@example.com", {"first"=>"Ruby", "last" => "SDK"});
# Define a to recipient
mb_obj.add_recipient(:to, "john.doe@example.com", {"first" => "John", "last" => "Doe"});
# Define a cc recipient
mb_obj.add_recipient(:cc, "sally.doe@example.com", {"first" => "Sally", "last" => "Doe"});
# Define the subject
mb_obj.set_subject("A message from the Ruby SDK using Message Builder!");
# Define the body of the message
mb_obj.set_text_body("This is the text body of the message!");
# Campaign and other headers
mb_obj.add_campaign_id("My-Awesome-Campaign");
mb_obj.add_custom_parameter("h:Customer-Id", "12345");
# Attach a file and rename it
mb_obj.add_attachment("/path/to/file/receipt_123491820.pdf", "Receipt.pdf");
# Schedule message in the future
mb_obj.set_delivery_time("tomorrow 8:00AM", "PST");
# Finally, send your message using the client
result = mg_client.send_message("sending_domain.com", mb_obj)
puts result.body.to_s
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 Mailgun para Ruby + Batch Message:
# First, instantiate the Mailgun Client with your API key
mg_client = Mailgun::Client.new("your-api-key")
mb_obj = Mailgun::BatchMessage.new(@mb_client, "example.com")
# Define the from address
mb_obj.set_from_address("me@example.com",
{"first"=>"Ruby",
"last" => "SDK"});
# Define the subject
mb_obj.set_subject("A message from the Ruby SDK using Message Builder!");
# Define the body of the message
mb_obj.set_text_body("Hello %recipient.first%,
This is the text body of the message
using recipient variables!
If you needed to reference the account-id
recipient variable, you could do it like
this: %account-id%.");
# Add several recipients
mb_obj.add_recipient(:to, "john.doe@example.com",
{"first" => "John",
"last" => "Doe",
"account-id" => 1234});
mb_obj.add_recipient(:to, "jane.doe@example.com",
{"first" => "Jane",
"last" => "Doe",
"account-id" => 5678});
mb_obj.add_recipient(:to, "bob.doe@example.com",
{"first" => "Bob",
"last" => "Doe",
"account-id" => 91011});
... etc ...
mb_obj.add_recipient(:to, "sally.doe@example.com",
{"first" => "Sally",
"last" => "Doe",
"account-id" => 121314});
# Send your message through the client
message_ids = mg_client.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 o nosso serviço 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.
Como cada implementação será um tanto única, confira a documentação do Github para ver exemplos de uso dessa classe.
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!
