class Mailgun::MessageBuilder

A Mailgun::MessageBuilder object is used to create a valid payload for the Mailgun API messages endpoint. If you prefer step by step message generation through your code, this class is for you.

See the Github documentation for full examples.

Attributes

counters[R]
message[R]

Public Class Methods

new() click to toggle source
# File lib/mailgun/messages/message_builder.rb, line 16
def initialize()
  @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

Public Instance Methods

add_attachment(attachment, filename=nil) click to toggle source

Adds a series of attachments, when called upon.

@param [String] attachment A file object for attaching as an attachment. @param [String] filename The filename you wish the attachment to be. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 92
def add_attachment(attachment, filename=nil)
  add_file(attachment, :attachment, filename)
end
add_campaign_id(campaign_id) click to toggle source

Add campaign IDs to message. Limit of 3 per message.

@param [String] campaign_id A defined campaign ID to add to the message. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 129
def add_campaign_id(campaign_id)
  if (@counters[:attributes][:campaign_id] == 3)
    raise ParameterError.new("Too many campaigns added to message.", campaign_id)
  end
  complex_setter("o:campaign", campaign_id)
  @counters[:attributes][:campaign_id] += 1
end
add_custom_parameter(name, data) click to toggle source

Add custom parameter to the message. A custom parameter is any parameter that is not yet supported by the SDK, but available at the API. Note: No validation is performed. Don't forget to prefix the parameter with o, h, or v.

@param [string] name A name for the custom parameter. @param [string] data A string of data for the parameter. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 212
def add_custom_parameter(name, data)
  complex_setter(name, data)
end
add_inline_image(inline_image, filename=nil) click to toggle source

Adds an inline image to the mesage object.

@param [String] inline_image A file object for attaching an inline image. @param [String] filename The filename you wish the inline image to be. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 102
def add_inline_image(inline_image, filename=nil)
  add_file(inline_image, :inline, filename)
end
add_recipient(recipient_type, address, variables=nil) click to toggle source

Adds a specific type of recipient to the message object.

@param [String] recipient_type The type of recipient. “to”, “cc”, “bcc” or “h:reply-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/message_builder.rb, line 36
def add_recipient(recipient_type, address, variables=nil)
  if (@counters[:recipients][recipient_type] == 1000)
    raise ParameterError.new("Too many recipients added to message.", address)
  end

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

  if @counters[:recipients].has_key?(recipient_type)
    @counters[:recipients][recipient_type] += 1
  end
end
add_tag(tag) click to toggle source

Add tags to message. Limit of 3 per message.

@param [String] tag A defined campaign ID to add to the message. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 142
def add_tag(tag)
  if (@counters[:attributes][:tag] == 3)
    raise ParameterError.new("Too many tags added to message.", tag)
  end
  complex_setter("o:tag", tag)
  @counters[:attributes][:tag] += 1
end
set_click_tracking(tracking) click to toggle source

Turn Click Tracking on and off, on a per message basis.

@param [String] tracking True, False, or HTML (for HTML only tracking) @return [void]

# File lib/mailgun/messages/message_builder.rb, line 164
def set_click_tracking(tracking)
  simple_setter("o:tracking-clicks", bool_lookup(tracking))
end
set_custom_data(name, data) click to toggle source

Add custom data to the message. The data should be either a hash or JSON encoded. The custom data will be added as a header to your message.

@param [string] name A name for the custom data. (Ex. X-Mailgun-<Name of Data>: {}) @param [Hash] data Either a hash or JSON string. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 188
def set_custom_data(name, data)
  if data.is_a?(Hash)
    data = data.to_json
  elsif data.is_a?(String)
    if not valid_json?(data)
      begin
        data = JSON.generate(data)
      rescue
        raise ParameterError.new("Failed to parse provided JSON.", data)
      end
    end
  end
  simple_setter("v:#{name}", data)
end
set_delivery_time(timestamp) click to toggle source

Enable Delivery delay on message. Specify an RFC2822 date, and Mailgun will not deliver the message until that date/time. For conversion options, see Ruby “Time”. Example: “October 25, 2013 10:00PM CST” will be converted to “Fri, 25 Oct 2013 22:00:00 -0600”.

@param [String] timestamp A date and time, including a timezone. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 176
def set_delivery_time(timestamp)
  time_str = DateTime.parse(timestamp)
  simple_setter("o:deliverytime", time_str.rfc2822)
end
set_dkim(dkim) click to toggle source

Turn DKIM on or off per message

@param [Boolean] dkim The boolean or string value(will fix itself) @return [void]

# File lib/mailgun/messages/message_builder.rb, line 120
def set_dkim(dkim)
  simple_setter("o:dkim", bool_lookup(dkim))
end
set_from_address(address, variables=nil) click to toggle source

Sets the from address for the message

@param [String] address The address of the sender. @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/message_builder.rb, line 55
def set_from_address(address, variables=nil)
  add_recipient(:from, address, variables)
end
set_html_body(html_body=nil) click to toggle source

Set a html body for the message object

@param [String] html_body The html body for the email. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 82
def set_html_body(html_body=nil)
  simple_setter(:html, html_body)
end
set_message_id(data) click to toggle source

Set the Message-Id header to a custom value. Don't forget to enclose the Message-Id in angle brackets, and ensure the @domain is present. Doesn't use simple or complex setters because it should not set value in an array.

@param [string] data A string of data for the parameter. Passing nil or empty string will delete h:Message-Id key and value from @message hash. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 223
def set_message_id(data)
  key = "h:Message-Id"

  if data.to_s.empty?
    @message.delete_if { |k, v| k == key }
  else
    @message[key] = data
  end
end
set_open_tracking(tracking) click to toggle source

Turn Open Tracking on and off, on a per message basis.

@param [Boolean] tracking Boolean true or false. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 155
def set_open_tracking(tracking)
  simple_setter("o:tracking-opens", bool_lookup(tracking))
end
set_subject(subject=nil) click to toggle source

Set a subject for the message object

@param [String] subject The subject for the email. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 64
def set_subject(subject=nil)
  simple_setter(:subject, subject)
end
set_test_mode(test_mode) click to toggle source

Send a message in test mode. (The message won't really be sent to the recipient)

@param [Boolean] test_mode The boolean or string value (will fix itself) @return [void]

# File lib/mailgun/messages/message_builder.rb, line 111
def set_test_mode(test_mode)
  simple_setter("o:testmode", bool_lookup(test_mode))
end
set_text_body(text_body=nil) click to toggle source

Set a text body for the message object

@param [String] text_body The text body for the email. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 73
def set_text_body(text_body=nil)
  simple_setter(:text, text_body)
end

Private Instance Methods

add_file(attachment, disposition, filename=nil) click to toggle source

Adds a file. Called through add_attachment and add_inline_image

@param [String] attachment A file object for attaching as an attachment. @param [Symbol] disposition The type of file: :attachment or :inline @param [String] filename The filename you wish the attachment to be. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 271
def add_file(attachment, disposition, filename=nil)
  if attachment.is_a?(String)
    attachment = File.open(attachment, "r")
  end
  if !(attachment.is_a?(File) || attachment.respond_to?(:read))
    raise ParameterError.new("Unable to access attachment file object.")
  end
  if !filename.nil?
    attachment.instance_variable_set :@original_filename, filename
    attachment.instance_eval "def original_filename; @original_filename; end"
  end
  complex_setter(disposition, attachment)
end
bool_lookup(value) click to toggle source

Converts boolean type to string

@param [String] value The item to convert @return [void]

# File lib/mailgun/messages/message_builder.rb, line 290
def bool_lookup(value)
  if value.is_a?(TrueClass) || value.is_a?(FalseClass)
    return value ? "yes" : "no"
  elsif value.is_a?(String)
    value.downcase!
    if ['true', 'yes', 'yep'].include? value
      return "yes"
    elsif ['false', 'no', 'nope'].include? value
      return "no"
    else
      return value
    end
  else
    return value
  end
end
complex_setter(parameter, value) click to toggle source

Sets values within the multidict, however, allows duplicate values for keys.

@param [String] parameter The message object parameter name. @param [String] value The value of the parameter. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 257
def complex_setter(parameter, value)
  if value.nil?
    @message[parameter] << ''
  else
    @message[parameter] << value
  end
end
parse_address(address, variables) click to toggle source

Parses the address and gracefully handles any missing parameters. The result should be something like: “'First Last' <person@domain.com>”

@param [String] address The email address to parse. @param [Hash] variables A list of recipient variables. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 325
def parse_address(address, variables)
  if variables.nil?
    return address
  end
  first, last = ''
  if variables.has_key?('first')
    first = variables['first']
    if variables.has_key?('last')
      last = variables['last']
    end
    full_name = "#{first} #{last}".strip
  end
  if defined?(full_name)
    return "'#{full_name}' <#{address}>"
  end
  return address
end
simple_setter(parameter, value) click to toggle source

Sets values within the multidict, however, prevents duplicate values for keys.

@param [String] parameter The message object parameter name. @param [String] value The value of the parameter. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 242
def simple_setter(parameter, value)
  if value.nil?
    @message[parameter] = ['']
  else
    @message[parameter] = [value]
  end
end
valid_json?(json_) click to toggle source

Validates whether the input is JSON.

@param [String] json_ The suspected JSON string. @return [void]

# File lib/mailgun/messages/message_builder.rb, line 311
def valid_json? json_
  JSON.parse(json_)
  return true
rescue JSON::ParserError
  return false
end