Class: Mailgun::MessageBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/mailgun/messages/message_builder.rb

Overview

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.

Direct Known Subclasses

BatchMessage

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ MessageBuilder

Returns a new instance of MessageBuilder.



16
17
18
19
20
21
22
23
24
25
26
27
 
# 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

Instance Attribute Details

#counters ⇒ Object (readonly)

Returns the value of attribute counters.



14
15
16
 
# File 'lib/mailgun/messages/message_builder.rb', line 14

def counters
  @counters
end

#message ⇒ Object (readonly)

Returns the value of attribute message.



14
15
16
 
# File 'lib/mailgun/messages/message_builder.rb', line 14

def message
  @message
end

Instance Method Details

#add_attachment(attachment, filename = nil) ⇒ void

This method returns an undefined value.

Adds a series of attachments, when called upon.

Parameters:

  • attachment (String) —

    A file object for attaching as an attachment.

  • filename (String) (defaults to: nil) —

    The filename you wish the attachment to be.



92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/mailgun/messages/message_builder.rb', line 92

def add_attachment(attachment, 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_eval "def original_filename; '#{filename}'; end"
  end
  complex_setter(:attachment, attachment)
end

#add_campaign_id(campaign_id) ⇒ void

This method returns an undefined value.

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

Parameters:

  • campaign_id (String) —

    A defined campaign ID to add to the message.



147
148
149
150
151
152
153
 
# File 'lib/mailgun/messages/message_builder.rb', line 147

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) ⇒ void

This method returns an undefined value.

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.

Parameters:

  • name (string) —

    A name for the custom parameter.

  • data (string) —

    A string of data for the paramter.



229
230
231
 
# File 'lib/mailgun/messages/message_builder.rb', line 229

def add_custom_parameter(name, data)
  complex_setter(name, data)
end

#add_inline_image(inline_image, filename = nil) ⇒ void

This method returns an undefined value.

Adds an inline image to the mesage object.

Parameters:

  • inline_image (String) —

    A file object for attaching an inline image.

  • filename (String) (defaults to: nil) —

    The filename you wish the inline image to be.



111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/mailgun/messages/message_builder.rb', line 111

def add_inline_image(inline_image, filename=nil)
  if inline_image.is_a?(String)
    inline_image = File.open(inline_image, "r")
  end
  if !inline_image.is_a?(File) || !inline_image.respond_to?(:read)
    raise ParameterError.new("Unable to access attachment file object.")
  end
  if !filename.nil?
    inline_image.instance_eval "def original_filename; '#{filename}'; end"
  end
  complex_setter(:inline, inline_image)
end

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

This method returns an undefined value.

Adds a specific type of recipient to the message object.

Parameters:

  • recipient_type (String) —

    The type of recipient. “to”, “cc”, “bcc” or “h:reply-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!



36
37
38
39
40
41
42
43
44
45
46
47
 
# 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) ⇒ void

This method returns an undefined value.

Add tags to message. Limit of 3 per message.

Parameters:

  • tag (String) —

    A defined campaign ID to add to the message.



160
161
162
163
164
165
166
 
# File 'lib/mailgun/messages/message_builder.rb', line 160

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) ⇒ void

This method returns an undefined value.

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

Parameters:

  • tracking (String) —

    True, False, or HTML (for HTML only tracking)



182
183
184
 
# File 'lib/mailgun/messages/message_builder.rb', line 182

def set_click_tracking(tracking)
  simple_setter("o:tracking-clicks", bool_lookup(tracking))
end

#set_custom_data(name, data) ⇒ void

This method returns an undefined value.

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.

Parameters:

  • name (string) —

    A name for the custom data. (Ex. X-Mailgun-<Name of Data>: {})

  • data (Hash) —

    Either a hash or JSON string.



206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/mailgun/messages/message_builder.rb', line 206

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) ⇒ void

This method returns an undefined value.

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”.

Parameters:

  • timestamp (String) —

    A date and time, including a timezone.



194
195
196
197
 
# File 'lib/mailgun/messages/message_builder.rb', line 194

def set_delivery_time(timestamp)
  time_str = DateTime.parse(timestamp)
  simple_setter("o:deliverytime", time_str.rfc2822)
end

#set_dkim(dkim) ⇒ void

This method returns an undefined value.

Turn DKIM on or off per message

Parameters:

  • dkim (Boolean) —

    The boolean or string value(will fix itself)



138
139
140
 
# File 'lib/mailgun/messages/message_builder.rb', line 138

def set_dkim(dkim)
  simple_setter("o:dkim", bool_lookup(dkim))
end

#set_from_address(address, variables = nil) ⇒ void

This method returns an undefined value.

Sets the from address for the message

Parameters:

  • address (String) —

    The address of the sender.

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

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



55
56
57
 
# 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) ⇒ void

This method returns an undefined value.

Set a html body for the message object

Parameters:

  • html_body (String) (defaults to: nil) —

    The html body for the email.



82
83
84
 
# File 'lib/mailgun/messages/message_builder.rb', line 82

def set_html_body(html_body=nil)
  simple_setter(:html, html_body)
end

#set_open_tracking(tracking) ⇒ void

This method returns an undefined value.

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

Parameters:

  • tracking (Boolean) —

    Boolean true or false.



173
174
175
 
# File 'lib/mailgun/messages/message_builder.rb', line 173

def set_open_tracking(tracking)
  simple_setter("o:tracking-opens", bool_lookup(tracking))
end

#set_subject(subject = nil) ⇒ void

This method returns an undefined value.

Set a subject for the message object

Parameters:

  • subject (String) (defaults to: nil) —

    The subject for the email.



64
65
66
 
# File 'lib/mailgun/messages/message_builder.rb', line 64

def set_subject(subject=nil)
  simple_setter(:subject, subject)
end

#set_test_mode(test_mode) ⇒ void

This method returns an undefined value.

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

Parameters:

  • test_mode (Boolean) —

    The boolean or string value (will fix itself)



129
130
131
 
# File 'lib/mailgun/messages/message_builder.rb', line 129

def set_test_mode(test_mode)
  simple_setter("o:testmode", bool_lookup(test_mode))
end

#set_text_body(text_body = nil) ⇒ void

This method returns an undefined value.

Set a text body for the message object

Parameters:

  • text_body (String) (defaults to: nil) —

    The text body for the email.



73
74
75
 
# File 'lib/mailgun/messages/message_builder.rb', line 73

def set_text_body(text_body=nil)
  simple_setter(:text, text_body)
end