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

Public: Creates a new MessageBuilder object.



13
14
15
16
17
18
19
20
 
# File 'lib/mailgun/messages/message_builder.rb', line 13

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.



10
11
12
 
# File 'lib/mailgun/messages/message_builder.rb', line 10

def counters
  @counters
end

#message ⇒ Object (readonly)

Returns the value of attribute message.



10
11
12
 
# File 'lib/mailgun/messages/message_builder.rb', line 10

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.



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

def add_attachment(attachment, filename = nil)
  add_file(:attachment, attachment, filename)
end

#add_campaign_id(campaign_id) ⇒ void

This method returns an undefined value.

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



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

def add_campaign_id(campaign_id)
  fail(Mailgun::ParameterError, 'Too many campaigns added to message.', campaign_id) if @counters[:attributes][:campaign_id] >= Mailgun::Chains::MAX_CAMPAIGN_IDS

  set_multi_complex('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.



297
298
299
 
# File 'lib/mailgun/messages/message_builder.rb', line 297

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

#add_inline_image(inline_image, filename = nil) ⇒ void

This method returns an undefined value.

Adds an inline image to the message object.



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

def add_inline_image(inline_image, filename = nil)
  add_file(:inline, inline_image, filename)
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.

WARNING: Setting ‘h:reply-to’ with add_recipient() is deprecated! Use ‘reply_to’ instead.



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/mailgun/messages/message_builder.rb', line 30

def add_recipient(recipient_type, address, variables = nil)
  if recipient_type == "h:reply-to"
    warn 'DEPRECATION: "add_recipient("h:reply-to", ...)" is deprecated. Please use "reply_to" instead.'
    return reply_to(address, variables)
  end

  if (@counters[:recipients][recipient_type] || 0) >= Mailgun::Chains::MAX_RECIPIENTS
    fail Mailgun::ParameterError, 'Too many recipients added to message.', address
  end

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

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

#add_tag(tag) ⇒ void

This method returns an undefined value.

Add tags to message. Limit of 10 per message.



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

def add_tag(tag)
  if @counters[:attributes][:tag] >= Mailgun::Chains::MAX_TAGS
    fail Mailgun::ParameterError, 'Too many tags added to message.', tag
  end
  set_multi_complex('o:tag', tag)
  @counters[:attributes][:tag] += 1
end

#amp_html(amp = nil) ⇒ void

This method returns an undefined value.

Set an AMP part for the message object



120
121
122
 
# File 'lib/mailgun/messages/message_builder.rb', line 120

def amp_html(amp = nil)
  set_single('amp-html', amp)
end

#body_html(html_body = nil) ⇒ void

This method returns an undefined value.

Set a html body for the message object



106
107
108
 
# File 'lib/mailgun/messages/message_builder.rb', line 106

def body_html(html_body = nil)
  set_multi_simple(:html, html_body)
end

#body_text(text_body = nil) ⇒ void

This method returns an undefined value.

Set a text body for the message object



92
93
94
 
# File 'lib/mailgun/messages/message_builder.rb', line 92

def body_text(text_body = nil)
  set_multi_simple(:text, text_body)
end

#deliver_at(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”.



240
241
242
243
 
# File 'lib/mailgun/messages/message_builder.rb', line 240

def deliver_at(timestamp)
  time_str = DateTime.parse(timestamp)
  set_multi_simple('o:deliverytime', time_str.rfc2822)
end

#dkim(mode) ⇒ void

This method returns an undefined value.

Turn DKIM on or off per message



168
169
170
 
# File 'lib/mailgun/messages/message_builder.rb', line 168

def dkim(mode)
  set_multi_simple('o:dkim', bool_lookup(mode))
end

#from(address, vars = nil) ⇒ void

This method returns an undefined value.

Sets the from address for the message



51
52
53
 
# File 'lib/mailgun/messages/message_builder.rb', line 51

def from(address, vars = nil)
  add_recipient(:from, address, vars)
end

#header(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.



257
258
259
260
261
262
263
264
265
 
# File 'lib/mailgun/messages/message_builder.rb', line 257

def header(name, data)
  fail(Mailgun::ParameterError, 'Header name for message must be specified') if name.to_s.empty?
  begin
    jsondata = make_json data
    set_single("h:#{name}", jsondata)
  rescue Mailgun::ParameterError
    set_single("h:#{name}", data)
  end
end

#list_unsubscribe(*variables) ⇒ void

This method returns an undefined value.

Adds a List-Unsubscribe for the message header.



146
147
148
 
# File 'lib/mailgun/messages/message_builder.rb', line 146

def list_unsubscribe(*variables)
  set_single('h:List-Unsubscribe', variables.map { |var| "<#{var}>" }.join(','))
end

#message_id(data = nil) ⇒ void

This method returns an undefined value.

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.



308
309
310
311
312
 
# File 'lib/mailgun/messages/message_builder.rb', line 308

def message_id(data = nil)
  key = 'h:Message-Id'
  return @message.delete(key) if data.to_s.empty?
  set_single(key, data)
end

#reply_to(address, variables = nil) ⇒ void

This method returns an undefined value.

Set the message’s Reply-To address.

Rationale: According to RFC, only one Reply-To address is allowed, so it is okay to bypass the set_multi_simple and set reply-to directly.



69
70
71
72
 
# File 'lib/mailgun/messages/message_builder.rb', line 69

def reply_to(address, variables = nil)
  compiled_address = parse_address(address, variables)
  header("reply-to", compiled_address)
end

#set_click_tracking(tracking) ⇒ Object

Depreciated: ‘set_click_tracking. is deprecated. Please use ’track_clicks’ instead.



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

def set_click_tracking(tracking)
  warn 'DEPRECATION: "set_click_tracking" is deprecated. Please use "track_clicks" instead.'
  track_clicks(tracking)
end

#set_custom_data(name, data) ⇒ Object

Deprecated: ‘set_custom_data’ is deprecated. Please use ‘header’ instead.



268
269
270
271
 
# File 'lib/mailgun/messages/message_builder.rb', line 268

def set_custom_data(name, data)
  warn 'DEPRECATION: "set_custom_data" is deprecated. Please use "header" instead.'
  header name, data
end

#set_delivery_time(timestamp) ⇒ Object

Deprecated: ‘set_delivery_time’ is deprecated. Please use ‘deliver_at’ instead.



246
247
248
249
 
# File 'lib/mailgun/messages/message_builder.rb', line 246

def set_delivery_time(timestamp)
  warn 'DEPRECATION: "set_delivery_time" is deprecated. Please use "deliver_at" instead.'
  deliver_at timestamp
end

#set_dkim(mode) ⇒ Object

Deprecated: ‘set_dkim’ is deprecated. Please use ‘dkim’ instead.



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

def set_dkim(mode)
  warn 'DEPRECATION: "set_dkim" is deprecated. Please use "dkim" instead.'
  dkim(mode)
end

#set_from_address(address, variables = nil) ⇒ Object

Deprecated: please use ‘from’ instead.



56
57
58
59
 
# File 'lib/mailgun/messages/message_builder.rb', line 56

def set_from_address(address, variables = nil)
  warn 'DEPRECATION: "set_from_address" is deprecated. Please use "from" instead.'
  from(address, variables)
end

#set_html_body(html_body = nil) ⇒ Object

Deprecated: Please use “body_html” instead.



111
112
113
114
 
# File 'lib/mailgun/messages/message_builder.rb', line 111

def set_html_body(html_body = nil)
  warn 'DEPRECATION: "set_html_body" is deprecated. Please use "body_html" instead.'
  body_html(html_body)
end

#set_message_id(data = nil) ⇒ Object

Deprecated: ‘set_message_id’ is deprecated. Use ‘message_id’ instead.



315
316
317
318
 
# File 'lib/mailgun/messages/message_builder.rb', line 315

def set_message_id(data = nil)
  warn 'DEPRECATION: "set_message_id" is deprecated. Please use "message_id" instead.'
  message_id data
end

#set_open_tracking(tracking) ⇒ Object

Deprecated: ‘set_open_tracking’ is deprecated. Please use ‘track_opens’ instead.



212
213
214
215
 
# File 'lib/mailgun/messages/message_builder.rb', line 212

def set_open_tracking(tracking)
  warn 'DEPRECATION: "set_open_tracking" is deprecated. Please use "track_opens" instead.'
  track_opens(tracking)
end

#set_subject(subj = nil) ⇒ Object

Deprecated: Please use “subject” instead.



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

def set_subject(subj = nil)
  warn 'DEPRECATION: "set_subject" is deprecated. Please use "subject" instead.'
  subject(subj)
end

#set_test_mode(mode) ⇒ Object

Deprecated: ‘set_test_mode’ is depreciated. Please use ‘test_mode’ instead.



159
160
161
162
 
# File 'lib/mailgun/messages/message_builder.rb', line 159

def set_test_mode(mode)
  warn 'DEPRECATION: "set_test_mode" is deprecated. Please use "test_mode" instead.'
  test_mode(mode)
end

#set_text_body(text_body = nil) ⇒ Object

Deprecated: Please use “body_text” instead.



97
98
99
100
 
# File 'lib/mailgun/messages/message_builder.rb', line 97

def set_text_body(text_body = nil)
  warn 'DEPRECATION: "set_text_body" is deprecated. Please use "body_text" instead.'
  body_text(text_body)
end

#subject(subj = nil) ⇒ void

This method returns an undefined value.

Set a subject for the message object



78
79
80
 
# File 'lib/mailgun/messages/message_builder.rb', line 78

def subject(subj = nil)
  set_multi_simple(:subject, subj)
end

#template(template_name = nil) ⇒ void

This method returns an undefined value.

Set name of a template stored via template API. See Templates for more information documentation.mailgun.com/en/latest/api-templates.html



326
327
328
329
330
 
# File 'lib/mailgun/messages/message_builder.rb', line 326

def template(template_name = nil)
  key = 'template'
  return @message.delete(key) if template_name.to_s.empty?
  set_single(key, template_name)
end

#template_text(mode) ⇒ void

This method returns an undefined value.

Turn off or on template rendering in the text part of the message in case of template sending.



348
349
350
 
# File 'lib/mailgun/messages/message_builder.rb', line 348

def template_text(mode)
  set_single('t:text', bool_lookup(mode))
end

#template_version(version = nil) ⇒ void

This method returns an undefined value.

Set specific template version.



337
338
339
340
341
 
# File 'lib/mailgun/messages/message_builder.rb', line 337

def template_version(version = nil)
  key = 't:version'
  return @message.delete(key) if version.to_s.empty?
  set_single(key, version)
end

#test_mode(mode) ⇒ void

This method returns an undefined value.

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



154
155
156
 
# File 'lib/mailgun/messages/message_builder.rb', line 154

def test_mode(mode)
  set_multi_simple('o:testmode', bool_lookup(mode))
end

#track_clicks(mode) ⇒ void

This method returns an undefined value.

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



221
222
223
224
225
 
# File 'lib/mailgun/messages/message_builder.rb', line 221

def track_clicks(mode)
  value = bool_lookup(mode)
  set_single('o:tracking-clicks', value)
  set_multi_simple('o:tracking', value)
end

#track_opens(mode) ⇒ void

This method returns an undefined value.

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



205
206
207
208
209
 
# File 'lib/mailgun/messages/message_builder.rb', line 205

def track_opens(mode)
  value = bool_lookup(mode)
  set_single('o:tracking-opens', value)
  set_multi_simple('o:tracking', value)
end

#variable(name, data) ⇒ void

This method returns an undefined value.

Attaches custom JSON data to the message. See the following doc page for more info. documentation.mailgun.com/user_manual.html#attaching-data-to-messages



280
281
282
283
284
285
286
287
288
 
# File 'lib/mailgun/messages/message_builder.rb', line 280

def variable(name, data)
  fail(Mailgun::ParameterError, 'Variable name must be specified') if name.to_s.empty?
  begin
    jsondata = make_json data
    set_single("v:#{name}", jsondata)
  rescue Mailgun::ParameterError
    set_single("v:#{name}", data)
  end
end