Class: Mailgun::BatchMessage

Inherits:
MessageBuilder show all
Defined in:
lib/mailgun/messages/batch_message.rb

Overview

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:

  1. Build your message using the Message Builder methods.

  2. Query your source and create an iterable list.

  3. Iterate through your source data, and add your recipients using the add_recipient() method.

  4. Call finalize() to flush any remaining recipients and obtain/store the message_ids for tracking purposes.

See the Github documentation for full examples.

Instance Attribute Summary collapse

Attributes inherited from MessageBuilder

#counters, #message

Instance Method Summary collapse

Methods inherited from MessageBuilder

#add_attachment, #add_campaign_id, #add_custom_parameter, #add_inline_image, #add_tag, #body_html, #body_text, #deliver_at, #dkim, #from, #header, #message_id, #set_click_tracking, #set_custom_data, #set_delivery_time, #set_dkim, #set_from_address, #set_html_body, #set_message_id, #set_open_tracking, #set_subject, #set_test_mode, #set_text_body, #subject, #test_mode, #track_clicks, #track_opens

Constructor Details

#initialize(client, domain) ⇒ BatchMessage

Public: Creates a new BatchMessage object.



27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/mailgun/messages/batch_message.rb', line 27

def initialize(client, domain)
  @client = client
  @recipient_variables = {}
  @domain = domain
  @message_ids = {}
  @message = Hash.new { |hash, key| hash[key] = [] }

  @counters = {
    recipients: { to: 0, cc: 0, bcc: 0 },
    attributes: { attachment: 0, campaign_id: 0, custom_option: 0, tag: 0 }
  }
end

Instance Attribute Details

#domain ⇒ Object (readonly)

Returns the value of attribute domain.



24
25
26
 
# File 'lib/mailgun/messages/batch_message.rb', line 24

def domain
  @domain
end

#message_ids ⇒ Object (readonly)

Returns the value of attribute message_ids.



24
25
26
 
# File 'lib/mailgun/messages/batch_message.rb', line 24

def message_ids
  @message_ids
end

#recipient_variables ⇒ Object (readonly)

Returns the value of attribute recipient_variables.



24
25
26
 
# File 'lib/mailgun/messages/batch_message.rb', line 24

def recipient_variables
  @recipient_variables
end

Instance Method Details

#add_recipient(recipient_type, address, variables = nil) ⇒ void

This method returns an undefined value.

Adds a specific type of recipient to the batch message object.

Parameters:

  • recipient_type (String) —

    The type of recipient. “to”.

  • address (String) —

    The email address of the recipient to add to the message object.

  • variables (Hash) (defaults to: nil) —

    A hash of the variables associated with the recipient. We recommend “first” and “last” at a minimum!



46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/mailgun/messages/batch_message.rb', line 46

def add_recipient(recipient_type, address, variables = nil)
  # send the message when we have 1000, not before
  send_message if @counters[:recipients][recipient_type] == Mailgun::Chains::MAX_RECIPIENTS

  compiled_address = parse_address(address, variables)
  complex_setter(recipient_type, compiled_address)

  store_recipient_variables(recipient_type, address, variables) if recipient_type != :from

  @counters[:recipients][recipient_type] += 1 if @counters[:recipients].key?(recipient_type)
end

#finalize ⇒ Hash

Always call this function after adding recipients. If less than 1000 are added, this function will ensure the batch is sent.

Returns:

  • (Hash) —

    A hash of ID’ => ‘# of Messages Sent’



62
63
64
65
 
# File 'lib/mailgun/messages/batch_message.rb', line 62

def finalize
  send_message if any_recipients_left?
  @message_ids
end