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.

Parameters:

  • attachment (String|File) —

    A file object for attaching as an attachment.

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

    The filename you wish the attachment to be.



131
132
133
 
# File 'lib/mailgun/messages/message_builder.rb', line 131

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.

Parameters:

  • campaign_id (String) —

    A defined campaign ID to add to the message.



172
173
174
175
176
177
178
179
180
 
# File 'lib/mailgun/messages/message_builder.rb', line 172

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

  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.

Parameters:

  • name (string) —

    A name for the custom parameter.

  • data (string) —

    A string of data for the parameter.



275
276
277
 
# File 'lib/mailgun/messages/message_builder.rb', line 275

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.

Parameters:

  • inline_image (String|File) —

    A file object for attaching an inline image.

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

    The filename you wish the inline image to be.



140
141
142
 
# File 'lib/mailgun/messages/message_builder.rb', line 140

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.

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!



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

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

Parameters:

  • tag (String) —

    A defined campaign ID to add to the message.



186
187
188
189
190
191
192
193
 
# File 'lib/mailgun/messages/message_builder.rb', line 186

def add_tag(tag)
  if @counters[:attributes][:tag] >= Mailgun::Chains::MAX_TAGS
    raise 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

Parameters:

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

    The AMP HTML for the email.



122
123
124
 
# File 'lib/mailgun/messages/message_builder.rb', line 122

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

Parameters:

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

    The html body for the email.



108
109
110
 
# File 'lib/mailgun/messages/message_builder.rb', line 108

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

Parameters:

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

    The text body for the email.



94
95
96
 
# File 'lib/mailgun/messages/message_builder.rb', line 94

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

Parameters:

  • timestamp (String) —

    A date and time, including a timezone.



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

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

Parameters:

  • mode (Boolean) —

    The boolean or string value(will fix itself)



164
165
166
 
# File 'lib/mailgun/messages/message_builder.rb', line 164

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

Parameters:

  • address (String) —

    The address of the sender.

  • variables (Hash) —

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



53
54
55
 
# File 'lib/mailgun/messages/message_builder.rb', line 53

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.

Parameters:

  • name (string) —

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

  • data (Hash) —

    Either a hash or JSON string.

Raises:



233
234
235
236
237
238
239
240
241
242
 
# File 'lib/mailgun/messages/message_builder.rb', line 233

def header(name, data)
  raise(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.

Parameters:

  • *variables (Array<String>) —

    Any number of url or mailto



148
149
150
 
# File 'lib/mailgun/messages/message_builder.rb', line 148

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.

Parameters:

  • data (string) (defaults to: nil) —

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



286
287
288
289
290
291
 
# File 'lib/mailgun/messages/message_builder.rb', line 286

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.

Parameters:

  • address (String) —

    The email address to provide as Reply-To.

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

    A hash of variables associated with the recipient.



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

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

#set_custom_data(name, data) ⇒ Object

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



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

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

#set_from_address(address, variables = nil) ⇒ Object

Deprecated: please use ‘from’ instead.



58
59
60
61
 
# File 'lib/mailgun/messages/message_builder.rb', line 58

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.



113
114
115
116
 
# File 'lib/mailgun/messages/message_builder.rb', line 113

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.



294
295
296
297
 
# File 'lib/mailgun/messages/message_builder.rb', line 294

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

#set_subject(subj = nil) ⇒ Object

Deprecated: Please use “subject” instead.



85
86
87
88
 
# File 'lib/mailgun/messages/message_builder.rb', line 85

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

#set_text_body(text_body = nil) ⇒ Object

Deprecated: Please use “body_text” instead.



99
100
101
102
 
# File 'lib/mailgun/messages/message_builder.rb', line 99

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

Parameters:

  • subject (String) —

    The subject for the email.



80
81
82
 
# File 'lib/mailgun/messages/message_builder.rb', line 80

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

Parameters:

  • tag (String) —

    A defined template name to use. Passing nil or empty string will delete template key and value from @message hash.



305
306
307
308
309
310
 
# File 'lib/mailgun/messages/message_builder.rb', line 305

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.

Parameters:

  • tracking (Boolean) —

    Boolean true or false.



329
330
331
 
# File 'lib/mailgun/messages/message_builder.rb', line 329

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.

Parameters:

  • tag (String) —

    A defined template name to use. Passing nil or empty string will delete template key and value from @message hash.



317
318
319
320
321
322
 
# File 'lib/mailgun/messages/message_builder.rb', line 317

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)

Parameters:

  • mode (Boolean) —

    The boolean or string value (will fix itself)



156
157
158
 
# File 'lib/mailgun/messages/message_builder.rb', line 156

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.

Parameters:

  • mode (String) —

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



209
210
211
212
213
 
# File 'lib/mailgun/messages/message_builder.rb', line 209

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.

Parameters:

  • tracking (Boolean) —

    Boolean true or false.



199
200
201
202
203
 
# File 'lib/mailgun/messages/message_builder.rb', line 199

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

Parameters:

  • name (String) —

    A name for the custom variable block.

  • data (String|Hash) —

    Either a string or a hash. If it is not valid JSON or can not be converted to JSON, ParameterError will be raised.

Raises:



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

def variable(name, data)
  raise(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