Class: MailBuilder
- Inherits:
-
Object
- Object
- MailBuilder
- Defined in:
- lib/mail_builder.rb,
lib/mail_builder/attachment.rb
Overview
MailBuilder is a library for building RFC compliant MIME messages, with support for text and HTML emails, as well as attachments.
Basic Usage:
mail = MailBuilder.new
mail.to = "[email protected]"
mail.text = "Body"
sendmail = IO.popen("#{`which sendmail`.chomp} -i -t", "w+")
sendmail.puts mail
sendmail.close
# or
require 'net/smtp'
Net::SMTP.start("smtp.address.com", 25) do |smtp|
smtp.(mail.to_s, mail.from, mail.to)
end
Defined Under Namespace
Classes: Attachment
Constant Summary collapse
- BOUNDARY_CHARS =
Boundary characters, slightly adapted from those allowed by rfc1341, representing:
ALPHA / DIGIT / "'" / "(" / ")" / "*" / "," / "-" / "." / "/" / ":"
((39..58).to_a + (65..90).to_a + (97..122).to_a).map { |_| _.chr }.freeze
- CHARSET =
'utf-8'.freeze
- RFC2047_REPLACEMENTS =
Printable characters which RFC 2047 says must be escaped.
[ ['?', '=%X' % ??.ord], ['_', '=%X' % ?_.ord], [' ', '_'], [/=$/, ''] ].freeze
Instance Attribute Summary collapse
-
#attachments ⇒ Object
readonly
Returns the value of attribute attachments.
-
#headers ⇒ Object
readonly
Returns the value of attribute headers.
-
#html ⇒ Object
Returns the value of attribute html.
-
#text ⇒ Object
Returns the value of attribute text.
Instance Method Summary collapse
-
#add_header(key, value) ⇒ Object
Adds a header value to the mailer’s headers, without removing previous values.
-
#attach(file, type = nil, headers = nil) ⇒ Object
Wrapper for attach_as, setting the attachment filename to the file’s basename.
-
#attach_as(file, name, type = nil, headers = nil) ⇒ Object
Adds an Attachment to the email.
- #attachments? ⇒ Boolean
-
#build ⇒ Object
(also: #to_s)
Builds the full email message suitable to be passed to Sendmail, Net::SMTP, etc.
-
#envelope_id ⇒ Object
Returns the envelope id for this mailer.
-
#get_header(key) ⇒ Object
(also: #[])
Retrieves a value from the mailer’s headers.
-
#header ⇒ Object
We define getters and setters for commonly used headers.
-
#initialize(options = {}) ⇒ MailBuilder
constructor
Accepts an options hash, setting text and html if provided, and setting any provided headers.
- #multipart? ⇒ Boolean
- #remove_header(key) ⇒ Object
-
#set_header(key, value) ⇒ Object
(also: #[]=)
Adds a header value to the mailer’s headers, replacing previous values.
Constructor Details
#initialize(options = {}) ⇒ MailBuilder
Accepts an options hash, setting text and html if provided, and setting any provided headers.
mailer = MailBuilder.new(:text => "Text", :to => "[email protected]", "X-Priority" => 1)
mailer.text # => "Text"
mailer.to # => "[email protected]"
mailer.get_header("X-Priority") # => 1
70 71 72 73 74 75 76 77 |
# File 'lib/mail_builder.rb', line 70 def initialize( = {}) @headers = [] @attachments = [] @text = nil @html = nil () end |
Instance Attribute Details
#attachments ⇒ Object (readonly)
Returns the value of attribute attachments.
59 60 61 |
# File 'lib/mail_builder.rb', line 59 def @attachments end |
#headers ⇒ Object (readonly)
Returns the value of attribute headers.
59 60 61 |
# File 'lib/mail_builder.rb', line 59 def headers @headers end |
#html ⇒ Object
Returns the value of attribute html.
58 59 60 |
# File 'lib/mail_builder.rb', line 58 def html @html end |
#text ⇒ Object
Returns the value of attribute text.
58 59 60 |
# File 'lib/mail_builder.rb', line 58 def text @text end |
Instance Method Details
#add_header(key, value) ⇒ Object
Adds a header value to the mailer’s headers, without removing previous values.
mailer.add_header("From", "[email protected]")
mailer.add_header("From", "[email protected]")
mailer.headers # => [["From", "[email protected]"], ["From", "[email protected]"]]
88 89 90 |
# File 'lib/mail_builder.rb', line 88 def add_header(key, value) @headers << [key.to_s, value] end |
#attach(file, type = nil, headers = nil) ⇒ Object
Wrapper for attach_as, setting the attachment filename to the file’s basename.
mailer.attach "some/file.pdf"
148 149 150 151 152 |
# File 'lib/mail_builder.rb', line 148 def attach(file, type = nil, headers = nil) file = Pathname(file) attach_as(file, file.basename, type, headers) end |
#attach_as(file, name, type = nil, headers = nil) ⇒ Object
Adds an Attachment to the email.
If file is an IO or File object, it’s contents will be read immediately, in case the mail will be delivered to an external service without access to the object. Otherwise, the attached file’s content will be read when the message is built.
If no type is provided, the MIME::Types library will be used to find a suitable content type.
mailer.attach "account.html"
mailer.attach_as StringIO.new("test"), "account.txt"
168 169 170 |
# File 'lib/mail_builder.rb', line 168 def attach_as(file, name, type = nil, headers = nil) @attachments << Attachment.new(file, name, type, headers) end |
#attachments? ⇒ Boolean
176 177 178 |
# File 'lib/mail_builder.rb', line 176 def @attachments.any? end |
#build ⇒ Object Also known as: to_s
Builds the full email message suitable to be passed to Sendmail, Net::SMTP, etc.
It sets the Mail-From header (used for tracking emails), date, and message id, and then assembles the headers, body, and attachments.
All expensive operations – generating boundaries, rendering views, reading attached files – are delayed until this method is called.
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 |
# File 'lib/mail_builder.rb', line 189 def build set_header("Mail-From", "#{ENV["USER"]}@localhost ENVID=#{envelope_id}") set_header("Date", Time.now.rfc2822) set_header("Message-ID", "<#{Time.now.to_f}.#{Process.pid}@#{get_header("from").to_s.split("@", 2)[1]}>") if multipart? set_header("Mime-Version", "1.0") if set_header("Content-Type", "multipart/mixed; boundary=\"#{}\"") else set_header("Content-Type", "multipart/alternative; boundary=\"#{body_boundary}\"") end end build_headers + build_body end |
#envelope_id ⇒ Object
Returns the envelope id for this mailer. The mail spec’s ENV_ID is used to provide a unique identifier that follows an email through it’s various states – including bounces – allowing it to be tracked.
125 126 127 |
# File 'lib/mail_builder.rb', line 125 def envelope_id @envelope_id ||= java.util.UUID.random_uuid.to_s end |
#get_header(key) ⇒ Object Also known as: []
Retrieves a value from the mailer’s headers.
mailer.get_header("to") # => "[email protected]"
97 98 99 |
# File 'lib/mail_builder.rb', line 97 def get_header(key) @headers.detect { |k, v| return v if k == key } end |
#header ⇒ Object
We define getters and setters for commonly used headers.
132 133 134 135 136 137 138 139 140 |
# File 'lib/mail_builder.rb', line 132 %w(from to cc bcc reply_to subject).each do |header| define_method(header) do get_header(header) end define_method(header + "=") do |value| set_header(header, value) end end |
#multipart? ⇒ Boolean
172 173 174 |
# File 'lib/mail_builder.rb', line 172 def multipart? || @html end |
#remove_header(key) ⇒ Object
102 103 104 |
# File 'lib/mail_builder.rb', line 102 def remove_header(key) @headers.reject! { |k,| k == key } end |
#set_header(key, value) ⇒ Object Also known as: []=
Adds a header value to the mailer’s headers, replacing previous values.
mailer.add_header("From", "[email protected]")
mailer.set_header("From", "[email protected]")
mailer.headers # => [["From", "[email protected]"]]
114 115 116 117 |
# File 'lib/mail_builder.rb', line 114 def set_header(key, value) remove_header(key) add_header(key, value) end |