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.



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

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.



12
13
14
 
# File 'lib/mailgun/messages/message_builder.rb', line 12

def counters
  @counters
end

#message ⇒ Object (readonly)

Returns the value of attribute message.



12
13
14
 
# File 'lib/mailgun/messages/message_builder.rb', line 12

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.



103
104
105
 
# File 'lib/mailgun/messages/message_builder.rb', line 103

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.



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

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

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



238
239
240
 
# File 'lib/mailgun/messages/message_builder.rb', line 238

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.



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

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.

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!



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

def add_recipient(recipient_type, address, variables = nil)
  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)
  complex_setter(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 3 per message.

Parameters:

  • tag (String) —

    A defined campaign ID to add to the message.



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

def add_tag(tag)
  if @counters[:attributes][:tag] >= Mailgun::Chains::MAX_TAGS
    fail Mailgun::ParameterError, 'Too many tags added to message.', tag
  end
  complex_setter('o:tag', tag)
  @counters[:attributes][:tag] += 1
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.



88
89
90
 
# File 'lib/mailgun/messages/message_builder.rb', line 88

def body_html(html_body = nil)
  simple_setter(: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.



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

def body_text(text_body = nil)
  simple_setter(: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.



202
203
204
205
 
# File 'lib/mailgun/messages/message_builder.rb', line 202

def deliver_at(timestamp)
  time_str = DateTime.parse(timestamp)
  simple_setter('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)



134
135
136
 
# File 'lib/mailgun/messages/message_builder.rb', line 134

def dkim(mode)
  simple_setter('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!



46
47
48
 
# File 'lib/mailgun/messages/message_builder.rb', line 46

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.



219
220
221
222
223
 
# File 'lib/mailgun/messages/message_builder.rb', line 219

def header(name, data)
  fail(Mailgun::ParameterError, 'Header name for message must be specified') if name.to_s.empty?
  jsondata = make_json data
  simple_setter("v:#{name}", jsondata)
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.



249
250
251
252
253
 
# File 'lib/mailgun/messages/message_builder.rb', line 249

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

#set_click_tracking(tracking) ⇒ Object

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



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

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.



226
227
228
229
 
# File 'lib/mailgun/messages/message_builder.rb', line 226

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.



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

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.



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

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.



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

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.



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

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.



256
257
258
259
 
# File 'lib/mailgun/messages/message_builder.rb', line 256

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.



176
177
178
179
 
# File 'lib/mailgun/messages/message_builder.rb', line 176

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.



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

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.



125
126
127
128
 
# File 'lib/mailgun/messages/message_builder.rb', line 125

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.



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

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.



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

def subject(subj = nil)
  simple_setter(:subject, subj)
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)



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

def test_mode(mode)
  simple_setter('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)



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

def track_clicks(mode)
  simple_setter('o:tracking-clicks', bool_lookup(mode))
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.



171
172
173
 
# File 'lib/mailgun/messages/message_builder.rb', line 171

def track_opens(mode)
  simple_setter('o:tracking-opens', bool_lookup(mode))
end