email_sender 1.0.2 → 1.1.0

data/README.rdoc

@@ -1,11 +1,12 @@
 = EmailSender Library
 
-EmailSender is an easy to use library to send email through SMTP server based on Net::SMTP library.
+EmailSender is an easy to use library to send email based on Net::SMTP.
+It supports the well-known encryption and authentication methods, and you can use it very easily with Gmail account.
 
   require 'email_sender'
 
   mailer = EmailSender.new(server: "smtp.mail.com", from: "sender@mail.com")
-  mailer.send(to: "receiver@mail.com", subject: "Test mail!", content: "This is a test mail!")
+  mailer.send(to: "receiver@mail.com", subject: "Test mail", content: "This is a test mail.")
 
 == Usage
 
@@ -15,7 +16,7 @@ You need specified the connection parameters to SMTP server on initialization:
   mailer = EmailSender.new(server: "smtp.mail.com", from: "Sender Name <sender@mail.com>")
 
   # encripted and authenticated connection
-  mailer = EmailSender.new(server: "smtp.mail.com", port: 465, from: "Sender Name <sender@mail.com>",
+  mailer = EmailSender.new(server: "smtp.mail.com", from: "Sender Name <sender@mail.com>",
                            enctype: :ssl_tls, authtype: :plain, username: "user.name", password: "secret")
 
 Easier way to using Gmail account:
@@ -27,7 +28,7 @@ Easier way to using Gmail account:
   # with full sender name
   mailer = EmailSender.new_gmail(from: "Sender Name <user.name@gmail.com>", password: "secret")
 
-  # with another sender email address and another domain (non gmail.com) account
+  # with another sender email address and another domain (not gmail.com) account
   mailer = EmailSender.new_gmail(from: "Sender Name <sender@othermail.com>",
                                  username: "user.name@company.com", password: "secret")
 
@@ -43,8 +44,8 @@ You can modify easily the parameters of mailer object:
 
 Send the mail to the +:to+, +:cc+ and +:bcc+ addresses with attachment:
 
-  mailer.send(to: "Receiver Name <receiver@mail.com>", subject: "Test mail!",
-              content: "This is a test mail!", attachment: "/path/to/file")
+  mailer.send(to: "Receiver Name <receiver@mail.com>", subject: "Test mail",
+              content: "This is a test mail.", attachment: "/path/to/file")
 
 The +:to+, +:cc+ and +:bcc+ keys accept an email address array so you can send the message to many receivers.
 And the +:attachment+ key accepts also file path array so you can attach more file:
@@ -52,7 +53,7 @@ And the +:attachment+ key accepts also file path array so you can attach more fi
   mailer.send(to: ["Receiver Name 1 <receiver1@mail.com>", "Receiver Name 2 <receiver2@mail.com>"],
               cc: ["Receiver Name 3 <receiver3@mail.com>", "Receiver Name 4 <receiver4@mail.com>"],
               bcc: [receiver5@mail.com, "receiver6@mail.com", "receiver7@mail.com"],
-              subject: "Test mail!", content: "This is a test mail!",
+              subject: "Test mail", content: "This is a test mail.",
               attachment: ["/path/to/file1", "/path/to/file2", "/path/to/file3"])
 
 If there are not specified the +:to+, +:cc+ and +:bcc+ addresses on sending use the initialized default addresses:
@@ -63,7 +64,7 @@ If there are not specified the +:to+, +:cc+ and +:bcc+ addresses on sending use
                            cc: ["Receiver Name 2 <receiver2@mail.com>", "Receiver Name 3 <receiver3@mail.com>"])
 
   # send email to the default addresses
-  mailer.send(subject: "Test mail!", content: "This is a test mail!")
+  mailer.send(subject: "Test mail", content: "This is a test mail.")
 
 You can specify the content type which is +'text/plain'+ by default:
 
@@ -71,15 +72,15 @@ You can specify the content type which is +'text/plain'+ by default:
               content: "<img src='http://upload.wikimedia.org/wikipedia/commons/7/73/Ruby_logo.svg'/>",
               conttype: "text/html")
 
-The library has implemented threadsafe and support the character encoded strings of Ruby.
+The library has implemented threadsafe and support the character encoded messages.
 
 == Installation
 
-  sudo gem install email_sender
+  gem install email_sender
 
 == Requirements
 
-ruby1.9.1
+ruby1.9.1 or greater
 
 == License
 

data/VERSION

@@ -1 +1 @@
-1.0.2
+1.1.0

data/lib/email_sender.rb

@@ -15,10 +15,8 @@
 # <http://www.gnu.org/licenses/>.
 
 
-require 'openssl'
 require 'net/smtp'
 
-
 # == Usage
 #   mailer = EmailSender.new(server: "smtp.mail.com", from: "sender@mail.com")
 #   mailer = EmailSender.new(server: "smtp.mail.com", port: 465, from: Sender Name <"sender@mail.com">,
@@ -27,17 +25,17 @@ require 'net/smtp'
 #   mailer = EmailSender.new_gmail(username: "user.name", password: "secret")
 #   mailer = EmailSender.new_gmail(from: "Sender Name <user.name@gmail.com>", password: "secret")
 #
-#   mailer.send(to: "receiver@mail.com", subject: "Test mail!", content: "This is a test mail!")
+#   mailer.send(to: "receiver@mail.com", subject: "Test mail", content: "This is a test mail.")
 #   mailer.send(to: "Receiver Name 1 <receiver1@mail.com>", cc: "Receiver Name 2 <receiver2@mail.com>",
-#     subject: "Test mail!", content: "This is a test mail!", attachment: "/path/to/file")
+#     subject: "Test mail", content: "This is a test mail.", attachment: "/path/to/file")
 # See the README for more useful examples!
 class EmailSender
   # Major version number
   VERSION_MAJOR = 1
   # Minor version number
-  VERSION_MINOR = 0
+  VERSION_MINOR = 1
   # Tiny version number
-  VERSION_TINY  = 2
+  VERSION_TINY  = 0
   # Version number
   VERSION_CODE  = (VERSION_MAJOR << 16) | (VERSION_MINOR << 8) | VERSION_TINY
   # Version string
@@ -48,7 +46,7 @@ class EmailSender
   Settings = Struct.new(:server, :port, :domain, :esmtp, :enctype, :authtype,
     :username, :password, :from_addr, :to_addrs, :cc_addrs, :bcc_addrs) #:nodoc:
 
-  # Create a new mailer object and initialize connection parameters to SMTP server.
+  # Create a new object and initialize connection parameters.
   #   +-----------------------------------------------------------------------------------+
   #   |                             Initialization Parameters                             |
   #   +------------+-------------------------------------------+--------------------------+
@@ -67,39 +65,44 @@ class EmailSender
   #   |:cc         |<string>, <array of string>                |[]                        |
   #   |:bcc        |<string>, <array of string>                |[]                        |
   #   +------------+-------------------------------------------+--------------------------+
-  def initialize(params)
+  # If you do not give any parameters, the instance does not initialize, and the #send() method will do nothing
+  # and return with a nil. You can set and modify the parameters later with the #renew() or #renew_gmail() methods.
+  def initialize(params={})
     renew(params)
   end
 
-  # Update the connection parameters to SMTP server.
-  # See the ::new method for initialization parameters.
-  def renew(params)
-    settings = Settings.new
-    settings.from_addr = parse_addr(params[:from])
-    settings.to_addrs = parse_addrs(*params[:to])
-    settings.cc_addrs = parse_addrs(*params[:cc])
-    settings.bcc_addrs = parse_addrs(*params[:bcc])
-    settings.domain = params[:domain] || settings.from_addr.last.split('@').last
-    settings.esmtp = params[:esmtp] != :disabled and params[:esmtp] != false
-    settings.enctype = params[:enctype]
-    authtype = params[:authtype]
-    username = params[:username]
-    password = params[:password]
-    if password and username and authtype and authtype != :none
-      settings.authtype = authtype
-      settings.username = username.encode(Encoding::UTF_8)
-      settings.password = password.encode(Encoding::UTF_8)
-    end
-    settings.server = params[:server].encode(Encoding::UTF_8)
-    settings.port = params[:port] || case settings.enctype
-      when :starttls then Net::SMTP.default_submission_port
-      when :ssl_tls then Net::SMTP.default_tls_port
-      else Net::SMTP.default_port
+  # Update the connection parameters.
+  # See the ::new() method for initialization parameters.
+  def renew(params={})
+    server, from = params[:server], params[:from]
+    if server and from
+      settings = Settings.new
+      settings.from_addr = parse_addr(from)
+      settings.to_addrs = parse_addrs(*params[:to])
+      settings.cc_addrs = parse_addrs(*params[:cc])
+      settings.bcc_addrs = parse_addrs(*params[:bcc])
+      settings.domain = params[:domain] || settings.from_addr.first.split('@').last
+      settings.esmtp = params[:esmtp] != :disabled and params[:esmtp] != false
+      settings.enctype = params[:enctype]
+      authtype, username, password = params[:authtype], params[:username], params[:password]
+      if password and username and authtype and authtype != :none
+        settings.authtype = authtype
+        settings.username = username.encode(Encoding::UTF_8)
+        settings.password = password.encode(Encoding::UTF_8)
+      end
+      settings.server = server.encode(Encoding::UTF_8)
+      settings.port = params[:port] || case settings.enctype
+        when :starttls then Net::SMTP.default_submission_port
+        when :ssl_tls then Net::SMTP.default_tls_port
+        else Net::SMTP.default_port
+      end
+      @settings = settings
+    else
+      @settings = nil
     end
-    @settings = settings
   end
 
-  # Create a new mailer object and initialize connection parameters to Gmail server.
+  # Create a new object and initialize connection parameters to Gmail server.
   #   +-----------------------------------------------------------------------------------+
   #   |                          Gmail Initialization Parameters                          |
   #   +------------+-------------------------------------------+--------------------------+
@@ -112,38 +115,43 @@ class EmailSender
   #   |:cc         |<string>, <array of string>                |[]                        |
   #   |:bcc        |<string>, <array of string>                |[]                        |
   #   +------------+-------------------------------------------+--------------------------+
-  def self.new_gmail(params)
+  # If you do not give any parameters, the instance does not initialize, and the #send() method will do nothing
+  # and return with a nil. You can set and modify the parameters later with the #renew() or #renew_gmail() methods.
+  def self.new_gmail(params={})
     instance = allocate()
     instance.renew_gmail(params)
     instance
   end
 
   # Update the connection parameters to Gmail server.
-  # See the ::new_gmail method for Gmail initialization parameters.
-  def renew_gmail(params)
-    params = params.dup
-    params[:server] = 'smtp.gmail.com'
-    params[:port] = 465
-    params[:domain] = 'gmail.com'
-    params[:esmtp] = :enabled
-    params[:enctype] = :ssl_tls
-    params[:authtype] = :plain
-    username = params[:username]
-    from = params[:from]
-    if username
-      username = username.encode(Encoding::UTF_8)
-      params[:username] = username << '@gmail.com' unless username.include?('@')
-      params[:from] = username unless from
-    end
-    if from
-      from_name, from_addr = parse_addr(from)
-      unless from_addr.include?('@')
-        from_addr << '@gmail.com'
-        params[:from] = from_name ? "#{from_name} <#{from_addr}>" : from_addr
+  # See the ::new_gmail() method for Gmail initialization parameters.
+  def renew_gmail(params={})
+    username, password, from = params[:username], params[:password], params[:from]
+    if password and (username or from)
+      params = params.dup
+      params[:server] = 'smtp.gmail.com'
+      params[:port] = 465
+      params[:domain] = 'gmail.com'
+      params[:esmtp] = :enabled
+      params[:enctype] = :ssl_tls
+      params[:authtype] = :plain
+      if username
+        username = username.encode(Encoding::UTF_8)
+        params[:username] = username << '@gmail.com' unless username.include?('@')
+        params[:from] = username unless from
       end
-      params[:username] = from_addr unless username
+      if from
+        from_addr, from_name = parse_addr(from)
+        unless from_addr.include?('@')
+          from_addr << '@gmail.com'
+          params[:from] = from_name ? "#{from_name} <#{from_addr}>" : from_addr
+        end
+        params[:username] = from_addr unless username
+      end
+      renew(params)
+    else
+      renew()
     end
-    renew(params)
   end
 
   # Send an email with the specified parameters.
@@ -160,103 +168,111 @@ class EmailSender
   #   |:conttype   |<string>                                   |'text/plain'              |
   #   |:attachment |<string>, <array of string>                |[]                        |
   #   +------------+-------------------------------------------+--------------------------+
+  # After a successful email sending it returns with a truth value (not nil and not false).
+  # If there is not any valid recipient email address or the object is not initialized, then it does nothing
+  # and returns with a nil. Anyway if any error occured during the sending, the Net::SMTP library throw an exception.
+  #
   # See the README for more information!
   def send(params={})
     settings = @settings
-    subject = params[:subject] || ''
-    content = params[:content] || subject
-    conttype = params[:conttype] || 'text/plain'
-    attachment = *params[:attachment]
-    to = *params[:to]
-    cc = *params[:cc]
-    bcc = *params[:bcc]
-    if to.empty? and cc.empty? and bcc.empty?
-      to_addrs = settings.to_addrs
-      cc_addrs = settings.cc_addrs
-      bcc_addrs = settings.bcc_addrs
-    else
-      to_addrs = parse_addrs(*to)
-      cc_addrs = parse_addrs(*cc)
-      bcc_addrs = parse_addrs(*bcc)
-    end
-    unless to_addrs.empty?
-      subject = subject.encode(Encoding::UTF_8)
-      content = content.encode(Encoding::UTF_8)
-      smtp = Net::SMTP.new(settings.server, settings.port)
-      smtp.disable_starttls
-      smtp.disable_tls
-      case settings.enctype
-        when :starttls_auto then smtp.enable_starttls_auto
-        when :starttls then smtp.enable_starttls
-        when :ssl_tls then smtp.enable_tls
+    if settings
+      subject = params[:subject] || ''
+      content = params[:content] || subject
+      conttype = params[:conttype] || 'text/plain'
+      attachment = *params[:attachment]
+      to = *params[:to]
+      cc = *params[:cc]
+      bcc = *params[:bcc]
+      if to.empty? and cc.empty? and bcc.empty?
+        to_addrs = settings.to_addrs
+        cc_addrs = settings.cc_addrs
+        bcc_addrs = settings.bcc_addrs
+      else
+        to_addrs = parse_addrs(*to)
+        cc_addrs = parse_addrs(*cc)
+        bcc_addrs = parse_addrs(*bcc)
       end
-      smtp.esmtp = settings.esmtp
-      message_id = nil
-      smtp.start(settings.domain, settings.username, settings.password, settings.authtype) do
-        from_name, from_addr = settings.from_addr
-        smtp.open_message_stream(from_addr, *to_addrs.keys, *cc_addrs.keys, *bcc_addrs.keys) do |stream|
-          now = Time.now
-          random_id = '%04x%04x.%08x.%08x.%08x' % [Process.pid & 0xFFFF, Thread.current.object_id & 0xFFFF,
-            now.tv_sec & 0xFFFF_FFFF, now.tv_nsec, rand(0x1_0000_0000)]
-          message_id = "#{random_id}@#{settings.domain}"
-          boundary = "boundary0_#{random_id}"
-          stream.puts("Message-ID: <#{message_id}>")
-          stream.puts(now.strftime('Date: %a, %d %b %Y %H:%M:%S %z'))
-          stream.puts("From: " << (from_name ? (from_name.ascii_only? ? "#{from_name} <#{from_addr}>" :
-            "=?utf-8?B?#{[from_name].pack('m0')}?= <#{from_addr}>") : from_addr))
-          to_str = ''
-          to_addrs.each do |addr, name|
-            to = name ? "#{name.ascii_only? ? name : "=?utf-8?B?#{[name].pack('m0')}?="} <#{addr}>" : addr
-            to_str << (to_str.empty? ? "To: #{to}" : ",\n\t#{to}")
-          end
-          stream.puts(to_str) unless to_str.empty?
-          cc_str = ''
-          cc_addrs.each do |addr, name|
-            cc = name ? "#{name.ascii_only? ? name : "=?utf-8?B?#{[name].pack('m0')}?="} <#{addr}>" : addr
-            cc_str << (cc_str.empty? ? "CC: #{cc}" : ",\n\t#{cc}")
-          end
-          stream.puts(cc_str) unless cc_str.empty?
-          stream.puts("Subject: " << (subject.ascii_only? ? subject : "=?utf-8?B?#{[subject].pack('m0')}?="))
-          stream.puts("MIME-Version: 1.0")
-          unless attachment.empty?
-            stream.puts("Content-Type: multipart/mixed; boundary=\"#{boundary}\"")
-            stream.puts
-            stream.puts("This is a multi-part message in MIME format.")
-            stream.puts("--#{boundary}")
-          end
-          stream.puts("Content-Type: #{conttype}; charset=#{content.ascii_only? ? 'us-ascii' : 'utf-8'}")
-          stream.puts("Content-Transfer-Encoding: base64")
-          stream.puts
-          stream.print([content].pack('m57'))
-          unless attachment.empty?
-            attachment.each do |file|
-              file = file.encode(Encoding::UTF_8)
-              basename = File.basename(file)
-              filename = basename.ascii_only? ? basename : "=?utf-8?B?#{[basename].pack('m0')}?="
-              stream.puts("--#{boundary}")
-              stream.puts("Content-Type: application/octet-stream; name=\"#{filename}\"")
-              stream.puts("Content-Transfer-Encoding: base64")
-              stream.puts("Content-Disposition: attachment; filename=\"#{filename}\"")
+      unless to_addrs.empty? and cc_addrs.empty? and bcc_addrs.empty?
+        subject = subject.encode(Encoding::UTF_8)
+        content = content.encode(Encoding::UTF_8)
+        smtp = Net::SMTP.new(settings.server, settings.port)
+        smtp.disable_starttls
+        smtp.disable_tls
+        case settings.enctype
+          when :starttls_auto then smtp.enable_starttls_auto
+          when :starttls then smtp.enable_starttls
+          when :ssl_tls then smtp.enable_tls
+        end
+        smtp.esmtp = settings.esmtp
+        message_id = nil
+        smtp.start(settings.domain, settings.username, settings.password, settings.authtype) do
+          from_addr, from_name = settings.from_addr
+          smtp.open_message_stream(from_addr, *to_addrs.keys, *cc_addrs.keys, *bcc_addrs.keys) do |stream|
+            now = Time.now
+            random_id = '%04x%04x.%08x.%08x.%08x' % [Process.pid & 0xFFFF, Thread.current.object_id & 0xFFFF,
+              now.tv_sec & 0xFFFF_FFFF, now.tv_nsec, rand(0x1_0000_0000)]
+            message_id = "#{random_id}@#{settings.domain}"
+            boundary = "boundary0_#{random_id}"
+            stream.puts("Message-ID: <#{message_id}>")
+            stream.puts(now.strftime('Date: %a, %d %b %Y %H:%M:%S %z'))
+            stream.puts("From: " << (from_name ? (from_name.ascii_only? ? "#{from_name} <#{from_addr}>" :
+              "=?utf-8?B?#{[from_name].pack('m0')}?= <#{from_addr}>") : from_addr))
+            to_str = ''
+            to_addrs.each do |addr, name|
+              to = name ? "#{name.ascii_only? ? name : "=?utf-8?B?#{[name].pack('m0')}?="} <#{addr}>" : addr
+              to_str << (to_str.empty? ? "To: #{to}" : ",\n\t#{to}")
+            end
+            stream.puts(to_str) unless to_str.empty?
+            cc_str = ''
+            cc_addrs.each do |addr, name|
+              cc = name ? "#{name.ascii_only? ? name : "=?utf-8?B?#{[name].pack('m0')}?="} <#{addr}>" : addr
+              cc_str << (cc_str.empty? ? "CC: #{cc}" : ",\n\t#{cc}")
+            end
+            stream.puts(cc_str) unless cc_str.empty?
+            stream.puts("Subject: " << (subject.ascii_only? ? subject : "=?utf-8?B?#{[subject].pack('m0')}?="))
+            stream.puts("MIME-Version: 1.0")
+            unless attachment.empty?
+              stream.puts("Content-Type: multipart/mixed; boundary=\"#{boundary}\"")
               stream.puts
-              File.open(file) { |io| stream.print([io.read(ATTACHMENT_READ_CACHE)].pack('m57')) until io.eof? }
+              stream.puts("This is a multi-part message in MIME format.")
+              stream.puts("--#{boundary}")
+            end
+            stream.puts("Content-Type: #{conttype}; charset=#{content.ascii_only? ? 'us-ascii' : 'utf-8'}")
+            stream.puts("Content-Transfer-Encoding: base64")
+            stream.puts
+            stream.print([content].pack('m57'))
+            unless attachment.empty?
+              attachment.each do |file|
+                file = file.encode(Encoding::UTF_8)
+                basename = File.basename(file)
+                filename = basename.ascii_only? ? basename : "=?utf-8?B?#{[basename].pack('m0')}?="
+                stream.puts("--#{boundary}")
+                stream.puts("Content-Type: application/octet-stream; name=\"#{filename}\"")
+                stream.puts("Content-Transfer-Encoding: base64")
+                stream.puts("Content-Disposition: attachment; filename=\"#{filename}\"")
+                stream.puts
+                File.open(file) { |io| stream.print([io.read(ATTACHMENT_READ_CACHE)].pack('m57')) until io.eof? }
+              end
+              stream.puts("--#{boundary}--")
             end
-            stream.puts("--#{boundary}--")
           end
         end
+        message_id
       end
-      message_id
     end
   end
 
 private
   def parse_addr(str)
     str = str.encode(Encoding::UTF_8)
-    str.scan(/\A\s*(.*?)\s*<([^<]*?)>\s*\z/).first || [nil, (str.strip!; str)]
+    str.strip!
+    addr = str.scan(/\A(.*?)\s*<([^<]*?)>\z/).first
+    addr ? addr.reverse! : [str, nil]
   end
   def parse_addrs(*strs)
     addrs = {}
     strs.each do |str|
-      name, addr = parse_addr(str)
+      addr, name = parse_addr(str)
       addrs[addr] = name
     end
     addrs

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: email_sender
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,10 +9,12 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-19 00:00:00.000000000 Z
+date: 2012-12-27 00:00:00.000000000 Z
 dependencies: []
-description: EmailSender is a easy to use library to send email through SMTP server
-  based on Net::SMTP library.
+description: ! 'EmailSender is an easy to use library to send email based on Net::SMTP.
+
+  It supports the well-known encryption and authentication methods, and you can use
+  it very easily with GMail account.'
 email: bakonyi.peter@gmail.com
 executables: []
 extensions: []
@@ -44,8 +46,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.11
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: Easy to use library to send email through any SMTP server.
+summary: EmailSender is an easy to use library to send email.
 test_files: []