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, #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

Constructor Details

#initialize(client, domain) ⇒ BatchMessage

Returns a new instance of BatchMessage.



30
31
32
33
34
35
36
# File 'lib/mailgun/messages/batch_message.rb', line 30

def initialize(client, domain)
  @client = client
  @recipient_variables = {}
  @domain = domain
  @message_ids = {}
  super()
end

Instance Attribute Details

#domainObject (readonly)

Returns the value of attribute domain.



28
29
30
# File 'lib/mailgun/messages/batch_message.rb', line 28

def domain
  @domain
end

#message_idsObject (readonly)

Returns the value of attribute message_ids.



28
29
30
# File 'lib/mailgun/messages/batch_message.rb', line 28

def message_ids
  @message_ids
end

#recipient_variablesObject (readonly)

Returns the value of attribute recipient_variables.



28
29
30
# File 'lib/mailgun/messages/batch_message.rb', line 28

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!



45
46
47
48
49
50
51
52
53
54
55
56
57
58
# 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

#finalizeHash

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’



65
66
67
68
69
70
# File 'lib/mailgun/messages/batch_message.rb', line 65

def finalize()
  if any_recipients_left?
    send_message(@message)
  end
  @message_ids
end