Class: Mailgun::MessageBuilder
- Inherits:
-
Object
- Object
- Mailgun::MessageBuilder
- 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
Instance Attribute Summary collapse
-
#counters ⇒ Object
readonly
Returns the value of attribute counters.
-
#message ⇒ Object
readonly
Returns the value of attribute message.
Instance Method Summary collapse
-
#add_attachment(attachment, filename = nil) ⇒ void
Adds a series of attachments, when called upon.
-
#add_campaign_id(campaign_id) ⇒ void
Add campaign IDs to message.
-
#add_custom_parameter(name, data) ⇒ void
Add custom parameter to the message.
-
#add_inline_image(inline_image, filename = nil) ⇒ void
Adds an inline image to the mesage object.
-
#add_recipient(recipient_type, address, variables = nil) ⇒ void
Adds a specific type of recipient to the message object.
-
#add_tag(tag) ⇒ void
Add tags to message.
-
#body_html(html_body = nil) ⇒ void
Set a html body for the message object.
-
#body_text(text_body = nil) ⇒ void
Set a text body for the message object.
-
#deliver_at(timestamp) ⇒ void
Enable Delivery delay on message.
-
#dkim(mode) ⇒ void
Turn DKIM on or off per message.
-
#from(address, vars = nil) ⇒ void
Sets the from address for the message.
-
#header(name, data) ⇒ void
Add custom data to the message.
-
#initialize ⇒ MessageBuilder
constructor
Public: Creates a new MessageBuilder object.
-
#list_unsubscribe(*variables) ⇒ void
Adds a List-Unsubscribe for the message header.
-
#message_id(data = nil) ⇒ void
Set the Message-Id header to a custom value.
-
#reply_to(address, variables = nil) ⇒ void
Set the message’s Reply-To address.
-
#set_click_tracking(tracking) ⇒ Object
Depreciated: ‘set_click_tracking.
-
#set_custom_data(name, data) ⇒ Object
Deprecated: ‘set_custom_data’ is deprecated.
-
#set_delivery_time(timestamp) ⇒ Object
Deprecated: ‘set_delivery_time’ is deprecated.
-
#set_dkim(mode) ⇒ Object
Deprecated: ‘set_dkim’ is deprecated.
-
#set_from_address(address, variables = nil) ⇒ Object
Deprecated: please use ‘from’ instead.
-
#set_html_body(html_body = nil) ⇒ Object
Deprecated: Please use “body_html” instead.
-
#set_message_id(data = nil) ⇒ Object
Deprecated: ‘set_message_id’ is deprecated.
-
#set_open_tracking(tracking) ⇒ Object
Deprecated: ‘set_open_tracking’ is deprecated.
-
#set_subject(subj = nil) ⇒ Object
Deprecated: Please use “subject” instead.
-
#set_test_mode(mode) ⇒ Object
Deprecated: ‘set_test_mode’ is depreciated.
-
#set_text_body(text_body = nil) ⇒ Object
Deprecated: Please use “body_text” instead.
-
#subject(subj = nil) ⇒ void
Set a subject for the message object.
-
#test_mode(mode) ⇒ void
Send a message in test mode.
-
#track_clicks(mode) ⇒ void
Turn Click Tracking on and off, on a per message basis.
-
#track_opens(mode) ⇒ void
Turn Open Tracking on and off, on a per message basis.
-
#variable(name, data) ⇒ void
Attaches custom JSON data to the message.
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 end |
Instance Method Details
#add_attachment(attachment, filename = nil) ⇒ void
This method returns an undefined value.
Adds a series of attachments, when called upon.
123 124 125 |
# File 'lib/mailgun/messages/message_builder.rb', line 123 def (, filename = nil) add_file(: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.
176 177 178 179 180 181 |
# File 'lib/mailgun/messages/message_builder.rb', line 176 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.
283 284 285 |
# File 'lib/mailgun/messages/message_builder.rb', line 283 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 mesage object.
132 133 134 |
# File 'lib/mailgun/messages/message_builder.rb', line 132 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.
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 |
# File 'lib/mailgun/messages/message_builder.rb', line 32 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 3 per message.
187 188 189 190 191 192 193 |
# File 'lib/mailgun/messages/message_builder.rb', line 187 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 |
#body_html(html_body = nil) ⇒ void
This method returns an undefined value.
Set a html body for the message object
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
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”.
230 231 232 233 |
# File 'lib/mailgun/messages/message_builder.rb', line 230 def deliver_at() time_str = DateTime.parse() 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
162 163 164 |
# File 'lib/mailgun/messages/message_builder.rb', line 162 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
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.
247 248 249 250 251 252 253 254 255 |
# File 'lib/mailgun/messages/message_builder.rb', line 247 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.
140 141 142 |
# File 'lib/mailgun/messages/message_builder.rb', line 140 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.
294 295 296 297 298 |
# File 'lib/mailgun/messages/message_builder.rb', line 294 def (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.
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_click_tracking(tracking) ⇒ Object
Depreciated: ‘set_click_tracking. is deprecated. Please use ’track_clicks’ instead.
218 219 220 221 |
# File 'lib/mailgun/messages/message_builder.rb', line 218 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.
258 259 260 261 |
# File 'lib/mailgun/messages/message_builder.rb', line 258 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.
236 237 238 239 |
# File 'lib/mailgun/messages/message_builder.rb', line 236 def set_delivery_time() warn 'DEPRECATION: "set_delivery_time" is deprecated. Please use "deliver_at" instead.' deliver_at end |
#set_dkim(mode) ⇒ Object
Deprecated: ‘set_dkim’ is deprecated. Please use ‘dkim’ instead.
167 168 169 170 |
# File 'lib/mailgun/messages/message_builder.rb', line 167 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.
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.
301 302 303 304 |
# File 'lib/mailgun/messages/message_builder.rb', line 301 def (data = nil) warn 'DEPRECATION: "set_message_id" is deprecated. Please use "message_id" instead.' data end |
#set_open_tracking(tracking) ⇒ Object
Deprecated: ‘set_open_tracking’ is deprecated. Please use ‘track_opens’ instead.
204 205 206 207 |
# File 'lib/mailgun/messages/message_builder.rb', line 204 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.
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_test_mode(mode) ⇒ Object
Deprecated: ‘set_test_mode’ is depreciated. Please use ‘test_mode’ instead.
153 154 155 156 |
# File 'lib/mailgun/messages/message_builder.rb', line 153 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.
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
80 81 82 |
# File 'lib/mailgun/messages/message_builder.rb', line 80 def subject(subj = nil) set_multi_simple(: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)
148 149 150 |
# File 'lib/mailgun/messages/message_builder.rb', line 148 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.
213 214 215 |
# File 'lib/mailgun/messages/message_builder.rb', line 213 def track_clicks(mode) set_multi_simple('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.
199 200 201 |
# File 'lib/mailgun/messages/message_builder.rb', line 199 def track_opens(mode) set_multi_simple('o:tracking-opens', bool_lookup(mode)) 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
270 271 272 273 274 |
# File 'lib/mailgun/messages/message_builder.rb', line 270 def variable(name, data) fail(Mailgun::ParameterError, 'Variable name must be specified') if name.to_s.empty? jsondata = make_json data set_single("v:#{name}", jsondata) end |