class Mailgun::BatchMessage
A Mailgun::BatchMessage
object is used to create a valid payload for Batch Sending. Batch Sending can be difficult to implement, therefore this code makes it dead simple to send millions of messages in batches of 1,000 recipients per HTTP call.
For the curious, the class simply keeps track of recipient data (count, user variables), and fires the API payload on the 1,000th addition of a recipient.
The best way to use this class is:
-
Build your message using the Message Builder methods.
-
Query your source and create an iterable list.
-
Iterate through your source data, and add your recipients using the
add_recipient
() method. -
Call finalize() to flush any remaining recipients and obtain/store the
message_ids
for tracking purposes.
See the Github documentation for full examples.
Attributes
Public Class Methods
# File lib/mailgun/messages/batch_message.rb, line 30 def initialize(client, domain) @client = client @recipient_variables = {} @domain = domain @message_ids = {} super() end
Public Instance Methods
Adds a specific type of recipient to the batch message object.
@param [String] recipient_type The type of recipient. “to”. @param [String] address The email address of the recipient to add to the message object. @param [Hash] variables A hash of the variables associated with the recipient. We recommend “first” and “last” at a minimum! @return [void]
# File lib/mailgun/messages/batch_message.rb, line 45 def add_recipient(recipient_type, address, variables=nil) if (@counters[:recipients][recipient_type] == 1000) send_message(@message) end compiled_address = parse_address(address, variables) complex_setter(recipient_type, compiled_address) if recipient_type != :from store_recipient_variables(recipient_type, address, variables) end if @counters[:recipients].has_key?(recipient_type) @counters[:recipients][recipient_type] += 1 end end
Always call this function after adding recipients. If less than 1000 are added, this function will ensure the batch is sent.
@return [Hash] A hash of {'Message ID' => '# of Messages Sent'}
# File lib/mailgun/messages/batch_message.rb, line 65 def finalize() if any_recipients_left? send_message(@message) end @message_ids end
Private Instance Methods
This method determines if it's necessary to send another batch.
@return [Boolean]
# File lib/mailgun/messages/batch_message.rb, line 78 def any_recipients_left? if @counters[:recipients][:to] > 0 return true elsif @counters[:recipients][:cc] > 0 return true elsif @counters[:recipients][:bcc] > 0 return true else return false end end
This method stores recipient variables for each recipient added, if variables exist.
# File lib/mailgun/messages/batch_message.rb, line 124 def count_recipients() count = 0 @counters[:recipients].each { |a| count = a[1] + count} count end
This method resets the message object to prepare for the next batch of recipients.
# File lib/mailgun/messages/batch_message.rb, line 133 def reset_message() @message.delete("recipient-variables") @message.delete(:to) @message.delete(:cc) @message.delete(:bcc) @counters[:recipients][:to] = 0 @counters[:recipients][:cc] = 0 @counters[:recipients][:bcc] = 0 end
This method initiates a batch send to the API. It formats the recipient variables, posts to the API, gathers the message IDs, then flushes that data to prepare for the next batch. This method implements the Mailgun
Client
, thus, an exception will be thrown if a communication error occurs.
@return [Boolean]
# File lib/mailgun/messages/batch_message.rb, line 97 def send_message(message) simple_setter("recipient-variables", JSON.generate(@recipient_variables)) if @message.has_key?("recipient-variables") @message["recipient-variables"] = @message["recipient-variables"].first end if @message.has_key?("h:Reply-To") @message["h:Reply-To"] = @message["h:Reply-To"].first end response = @client.send_message(@domain, @message).to_h! message_id = response['id'].gsub(/\>|\</, '') @message_ids[message_id] = count_recipients() reset_message() end
This method stores recipient variables for each recipient added, if variables exist.
# File lib/mailgun/messages/batch_message.rb, line 114 def store_recipient_variables(recipient_type, address, variables) if not variables variables = {:id => @counters[:recipients][recipient_type]} end @recipient_variables[address] = variables end