mail 2.2.5 → 2.2.19

data/lib/mail/network/delivery_methods/sendmail.rb

@@ -1,57 +1,57 @@
 module Mail
   # A delivery method implementation which sends via sendmail.
-  # 
+  #
   # To use this, first find out where the sendmail binary is on your computer,
   # if you are on a mac or unix box, it is usually in /usr/sbin/sendmail, this will
   # be your sendmail location.
-  # 
+  #
   #   Mail.defaults do
   #     delivery_method :sendmail
   #   end
-  # 
+  #
   # Or if your sendmail binary is not at '/usr/sbin/sendmail'
-  # 
+  #
   #   Mail.defaults do
   #     delivery_method :sendmail, :location => '/absolute/path/to/your/sendmail'
   #   end
-  # 
+  #
   # Then just deliver the email as normal:
-  # 
+  #
   #   Mail.deliver do
   #     to 'mikel@test.lindsaar.net'
   #     from 'ada@test.lindsaar.net'
   #     subject 'testing sendmail'
   #     body 'testing sendmail'
   #   end
-  # 
+  #
   # Or by calling deliver on a Mail message
-  # 
+  #
   #   mail = Mail.new do
   #     to 'mikel@test.lindsaar.net'
   #     from 'ada@test.lindsaar.net'
   #     subject 'testing sendmail'
   #     body 'testing sendmail'
   #   end
-  # 
+  #
   #   mail.deliver!
   class Sendmail
-    
+
     def initialize(values)
       self.settings = { :location       => '/usr/sbin/sendmail',
                         :arguments      => '-i -t' }.merge(values)
     end
-    
+
     attr_accessor :settings
 
     def deliver!(mail)
       envelope_from = mail.return_path || mail.sender || mail.from_addrs.first
-      return_path = "-f \"#{envelope_from}\"" if envelope_from
+      return_path = "-f \"#{envelope_from.to_s.shellescape}\"" if envelope_from
 
       arguments = [settings[:arguments], return_path].compact.join(" ")
-      
-      Sendmail.call(settings[:location], arguments, mail.destinations.join(" "), mail)
+
+      Sendmail.call(settings[:location], arguments, mail.destinations.collect(&:shellescape).join(" "), mail)
     end
-    
+
     def Sendmail.call(path, arguments, destinations, mail)
       IO.popen("#{path} #{arguments} #{destinations}", "w+") do |io|
         io.puts mail.encoded.to_lf

data/lib/mail/network/delivery_methods/smtp.rb

@@ -34,6 +34,18 @@ module Mail
   #                              :enable_starttls_auto => true  }
   #   end
   #
+  # === Certificate verification
+  #
+  # When using TLS, some mail servers provide certificates that are self-signed
+  # or whose names do not exactly match the hostname given in the address.
+  # OpenSSL will reject these by default. The best remedy is to use the correct
+  # hostname or update the certificate authorities trusted by your ruby. If
+  # that isn't possible, you can control this behavior with
+  # an :openssl_verify_mode setting. Its value may be either an OpenSSL
+  # verify mode constant (OpenSSL::SSL::VERIFY_NONE), or a string containing
+  # the name of an OpenSSL verify mode (none, peer, client_once,
+  # fail_if_no_peer_cert).
+  #
   # === Others 
   # 
   # Feel free to send me other examples that were tricky
@@ -68,7 +80,9 @@ module Mail
                         :user_name            => nil,
                         :password             => nil,
                         :authentication       => nil,
-                        :enable_starttls_auto => true  }.merge!(values)
+                        :enable_starttls_auto => true,
+                        :openssl_verify_mode  => nil
+                      }.merge!(values)
     end
     
     attr_accessor :settings
@@ -95,16 +109,29 @@ module Mail
       
       smtp = Net::SMTP.new(settings[:address], settings[:port])
       if settings[:enable_starttls_auto]
-        smtp.enable_starttls_auto if smtp.respond_to?(:enable_starttls_auto) 
+        if smtp.respond_to?(:enable_starttls_auto) 
+          unless settings[:openssl_verify_mode]
+            smtp.enable_starttls_auto
+          else
+            openssl_verify_mode = settings[:openssl_verify_mode]
+            if openssl_verify_mode.kind_of?(String)
+              openssl_verify_mode = "OpenSSL::SSL::VERIFY_#{openssl_verify_mode.upcase}".constantize
+            end
+            context = Net::SMTP.default_ssl_context
+            context.verify_mode = openssl_verify_mode
+            smtp.enable_starttls_auto(context)
+          end
+        end
       end
       
+      response = nil
       smtp.start(settings[:domain], settings[:user_name], settings[:password], settings[:authentication]) do |smtp|
-        smtp.sendmail(message, envelope_from, destinations)
+        response = smtp.sendmail(message, envelope_from, destinations)
       end
-      
-      self
+
+      return settings[:return_response] ? response : self
     end
     
     
   end
-end
+end

data/lib/mail/network/delivery_methods/smtp_connection.rb

@@ -0,0 +1,74 @@
+module Mail
+  # == Sending Email with SMTP
+  # 
+  # Mail allows you to send emails using an open SMTP connection.  This is done by
+  # passing a created Net::SMTP object.  This way we can get better performance to
+  # our local mail server by reducing the number of connections at any one time.
+  #
+  # === Sending via SMTP server on Localhost
+  # 
+  # To send mail open a connection with Net::Smtp using any options you like
+  # === Delivering the email
+  # 
+  # Once you have the settings right, sending the email is done by:
+  #
+  #   smtp_conn = Net::SMTP.start(settings[:address], settings[:port])
+  #   Mail.defaults do
+  #     delivery_method :smtp_connection, { :connection => smtp_conn }
+  #   end
+  # 
+  #   Mail.deliver do
+  #     to 'mikel@test.lindsaar.net'
+  #     from 'ada@test.lindsaar.net'
+  #     subject 'testing sendmail'
+  #     body 'testing sendmail'
+  #   end
+  # 
+  # Or by calling deliver on a Mail message
+  # 
+  #   mail = Mail.new do
+  #     to 'mikel@test.lindsaar.net'
+  #     from 'ada@test.lindsaar.net'
+  #     subject 'testing sendmail'
+  #     body 'testing sendmail'
+  #   end
+  # 
+  #   mail.deliver!
+  class SMTPConnection
+
+    def initialize(values)
+      raise ArgumentError.new('A Net::SMTP object is required for this delivery method') if values[:connection].nil?
+      self.smtp = values[:connection]
+      self.settings = values
+    end
+    
+    attr_accessor :smtp
+    attr_accessor :settings
+    
+    # Send the message via SMTP.
+    # The from and to attributes are optional. If not set, they are retrieve from the Message.
+    def deliver!(mail)
+
+      # Set the envelope from to be either the return-path, the sender or the first from address
+      envelope_from = mail.return_path || mail.sender || mail.from_addrs.first
+      if envelope_from.blank?
+        raise ArgumentError.new('A sender (Return-Path, Sender or From) required to send a message') 
+      end
+      
+      destinations ||= mail.destinations if mail.respond_to?(:destinations) && mail.destinations
+      if destinations.blank?
+        raise ArgumentError.new('At least one recipient (To, Cc or Bcc) is required to send a message') 
+      end
+      
+      message ||= mail.encoded if mail.respond_to?(:encoded)
+      if message.blank?
+        raise ArgumentError.new('A encoded content is required to send a message')
+      end
+            
+      response = smtp.sendmail(message, envelope_from, destinations)
+      
+      settings[:return_response] ? response : self 
+    end
+        
+  end
+end

data/lib/mail/network/retriever_methods/base.rb

@@ -0,0 +1,63 @@
+# encoding: utf-8
+
+module Mail
+
+  class Retriever
+
+    # Get the oldest received email(s)
+    #
+    # Possible options:
+    #   count: number of emails to retrieve. The default value is 1.
+    #   order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
+    #
+    def first(options = {}, &block)
+      options ||= {}
+      options[:what] = :first
+      options[:count] ||= 1
+      find(options, &block)
+    end
+    
+    # Get the most recent received email(s)
+    #
+    # Possible options:
+    #   count: number of emails to retrieve. The default value is 1.
+    #   order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
+    #
+    def last(options = {}, &block)
+      options ||= {}
+      options[:what] = :last
+      options[:count] ||= 1
+      find(options, &block)
+    end
+    
+    # Get all emails.
+    #
+    # Possible options:
+    #   order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
+    #
+    def all(options = {}, &block)
+      options ||= {}
+      options[:count] = :all
+      find(options, &block)
+    end
+
+    # Find emails in the mailbox, and then deletes them. Without any options, the 
+    # five last received emails are returned.
+    #
+    # Possible options:
+    #   what:  last or first emails. The default is :first.
+    #   order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
+    #   count: number of emails to retrieve. The default value is 10. A value of 1 returns an
+    #          instance of Message, not an array of Message instances.
+    #   delete_after_find: flag for whether to delete each retreived email after find. Default
+    #           is true. Call #find if you would like this to default to false.
+    #
+    def find_and_delete(options = {}, &block)
+      options ||= {}
+      options[:delete_after_find] ||= true
+      find(options, &block)      
+    end 
+
+  end
+
+end

data/lib/mail/network/retriever_methods/imap.rb

@@ -1,18 +1,158 @@
+# encoding: utf-8
+
 module Mail
-  class IMAP
+  # The IMAP retriever allows to get the last, first or all emails from a IMAP server.
+  # Each email retrieved (RFC2822) is given as an instance of +Message+.
+  #
+  # While being retrieved, emails can be yielded if a block is given.
+  #
+  # === Example of retrieving Emails from GMail:
+  #
+  #   Mail.defaults do
+  #     retriever_method :imap, { :address             => "imap.googlemail.com",
+  #                               :port                => 993,
+  #                               :user_name           => '<username>',
+  #                               :password            => '<password>',
+  #                               :enable_ssl          => true }
+  #   end
+  #
+  #   Mail.all    #=> Returns an array of all emails
+  #   Mail.first  #=> Returns the first unread email
+  #   Mail.last   #=> Returns the first unread email
+  #
+  # You can also pass options into Mail.find to locate an email in your imap mailbox
+  # with the following options:
+  #
+  #   mailbox: name of the mailbox used for email retrieval. The default is 'INBOX'.
+  #   what:    last or first emails. The default is :first.
+  #   order:   order of emails returned. Possible values are :asc or :desc. Default value is :asc.
+  #   count:   number of emails to retrieve. The default value is 10. A value of 1 returns an
+  #            instance of Message, not an array of Message instances.
+  #
+  #   Mail.find(:what => :first, :count => 10, :order => :asc)
+  #   #=> Returns the first 10 emails in ascending order
+  #
+  class IMAP < Retriever
+    require 'net/imap'
     
     def initialize(values)
       self.settings = { :address              => "localhost",
-                        :port                 => 110,
+                        :port                 => 143,
                         :user_name            => nil,
                         :password             => nil,
                         :authentication       => nil,
                         :enable_ssl           => false }.merge!(values)
     end
-    
-    def IMAP.get_messages(&block)
-      # To be implemented
+
+    attr_accessor :settings
+
+    # Find emails in a IMAP mailbox. Without any options, the 10 last received emails are returned.
+    #
+    # Possible options:
+    #   mailbox: mailbox to search the email(s) in. The default is 'INBOX'.
+    #   what:    last or first emails. The default is :first.
+    #   order:   order of emails returned. Possible values are :asc or :desc. Default value is :asc.
+    #   count:   number of emails to retrieve. The default value is 10. A value of 1 returns an
+    #            instance of Message, not an array of Message instances.
+    #   delete_after_find: flag for whether to delete each retreived email after find. Default
+    #           is false. Use #find_and_delete if you would like this to default to true.
+    #
+    def find(options={}, &block)
+      options = validate_options(options)
+
+      start do |imap|
+        imap.select(options[:mailbox])
+
+        message_ids = imap.uid_search(options[:keys])
+        message_ids.reverse! if options[:what].to_sym == :last
+        message_ids = message_ids.first(options[:count]) if options[:count].is_a?(Integer)
+        message_ids.reverse! if (options[:what].to_sym == :last && options[:order].to_sym == :asc) ||
+                                (options[:what].to_sym != :last && options[:order].to_sym == :desc)
+
+        if block_given?
+          message_ids.each do |message_id|
+            fetchdata = imap.uid_fetch(message_id, ['RFC822'])[0]
+            new_message = Mail.new(fetchdata.attr['RFC822'])
+            new_message.mark_for_delete = true if options[:delete_after_find]
+            if block.arity == 3
+              yield new_message, imap, message_id
+            else
+              yield new_message
+            end
+            imap.uid_store(message_id, "+FLAGS", [Net::IMAP::DELETED]) if options[:delete_after_find] && new_message.is_marked_for_delete?
+          end
+          imap.expunge if options[:delete_after_find]
+        else
+          emails = []
+          message_ids.each do |message_id|
+            fetchdata = imap.uid_fetch(message_id, ['RFC822'])[0]
+            emails << Mail.new(fetchdata.attr['RFC822'])
+            imap.uid_store(message_id, "+FLAGS", [Net::IMAP::DELETED]) if options[:delete_after_find]
+          end
+          imap.expunge if options[:delete_after_find]
+          emails.size == 1 && options[:count] == 1 ? emails.first : emails
+        end
+      end
     end
-    
+
+    # Delete all emails from a IMAP mailbox
+    def delete_all(mailbox='INBOX')
+      mailbox ||= 'INBOX'
+      mailbox = Net::IMAP.encode_utf7(mailbox)
+
+      start do |imap|
+        imap.select(mailbox)
+        imap.uid_search(['ALL']).each do |message_id|
+          imap.uid_store(message_id, "+FLAGS", [Net::IMAP::DELETED])
+        end
+        imap.expunge
+      end
+    end
+
+    # Returns the connection object of the retrievable (IMAP or POP3)
+    def connection(&block)
+      raise ArgumentError.new('Mail::Retrievable#connection takes a block') unless block_given?
+
+      start do |imap|
+        yield imap
+      end
+    end
+
+    private
+
+      # Set default options
+      def validate_options(options)
+        options ||= {}
+        options[:mailbox] ||= 'INBOX'
+        options[:count]   ||= 10
+        options[:order]   ||= :asc
+        options[:what]    ||= :first
+        options[:keys]    ||= 'ALL'
+        options[:delete_after_find] ||= false
+        options[:mailbox] = Net::IMAP.encode_utf7(options[:mailbox])
+
+        options
+      end
+
+      # Start an IMAP session and ensures that it will be closed in any case.
+      def start(config=Mail::Configuration.instance, &block)
+        raise ArgumentError.new("Mail::Retrievable#imap_start takes a block") unless block_given?
+
+        imap = Net::IMAP.new(settings[:address], settings[:port], settings[:enable_ssl], nil, false)
+        if settings[:authentication].nil?
+          imap.login(settings[:user_name], settings[:password])
+        else
+          # Note that Net::IMAP#authenticate('LOGIN', ...) is not equal with Net::IMAP#login(...)!
+          # (see also http://www.ensta.fr/~diam/ruby/online/ruby-doc-stdlib/libdoc/net/imap/rdoc/classes/Net/IMAP.html#M000718)
+          imap.authenticate(settings[:authentication], settings[:user_name], settings[:password])
+        end
+
+        yield imap
+      ensure
+        if defined?(imap) && imap && !imap.disconnected?
+          imap.disconnect
+        end
+      end
+
   end
-end
+end

data/lib/mail/network/retriever_methods/pop3.rb

@@ -31,7 +31,7 @@ module Mail
   #   Mail.find(:what => :first, :count => 10, :order => :asc)
   #   #=> Returns the first 10 emails in ascending order
   # 
-  class POP3
+  class POP3 < Retriever
     require 'net/pop'
 
     def initialize(values)
@@ -45,43 +45,6 @@ module Mail
     
     attr_accessor :settings
     
-    # Get the oldest received email(s)
-    #
-    # Possible options:
-    #   count: number of emails to retrieve. The default value is 1.
-    #   order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
-    #
-    def first(options = {}, &block)
-      options ||= {}
-      options[:what] = :first
-      options[:count] ||= 1
-      find(options, &block)
-    end
-    
-    # Get the most recent received email(s)
-    #
-    # Possible options:
-    #   count: number of emails to retrieve. The default value is 1.
-    #   order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
-    #
-    def last(options = {}, &block)
-      options ||= {}
-      options[:what] = :last
-      options[:count] ||= 1
-      find(options, &block)
-    end
-    
-    # Get all emails.
-    #
-    # Possible options:
-    #   order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
-    #
-    def all(options = {}, &block)
-      options ||= {}
-      options[:count] = :all
-      find(options, &block)
-    end
-    
     # Find emails in a POP3 mailbox. Without any options, the 5 last received emails are returned.
     #
     # Possible options:
@@ -89,12 +52,15 @@ module Mail
     #   order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
     #   count: number of emails to retrieve. The default value is 10. A value of 1 returns an
     #          instance of Message, not an array of Message instances.
+    #   delete_after_find: flag for whether to delete each retreived email after find. Default
+    #           is false. Use #find_and_delete if you would like this to default to true.
     #
     def find(options = {}, &block)
       options = validate_options(options)
       
       start do |pop3|
         mails = pop3.mails
+        pop3.reset # Clears all "deleted" marks. This prevents non-explicit/accidental deletions due to server settings.
         mails.sort! { |m1, m2| m2.number <=> m1.number } if options[:what] == :last
         mails = mails.first(options[:count]) if options[:count].is_a? Integer
         
@@ -105,12 +71,16 @@ module Mail
         
         if block_given?
           mails.each do |mail|
-            yield Mail.new(mail.pop)
+            new_message = Mail.new(mail.pop)
+            new_message.mark_for_delete = true if options[:delete_after_find]
+            yield new_message
+            mail.delete if options[:delete_after_find] && new_message.is_marked_for_delete? # Delete if still marked for delete
           end
         else
           emails = []
           mails.each do |mail|
             emails << Mail.new(mail.pop)
+            mail.delete if options[:delete_after_find]
           end
           emails.size == 1 && options[:count] == 1 ? emails.first : emails
         end
@@ -127,6 +97,15 @@ module Mail
         end
       end
     end
+
+    # Returns the connection object of the retrievable (IMAP or POP3)
+    def connection(&block)
+      raise ArgumentError.new('Mail::Retrievable#connection takes a block') unless block_given?
+
+      start do |pop3|
+        yield pop3
+      end
+    end
     
   private
   
@@ -136,11 +115,14 @@ module Mail
       options[:count] ||= 10
       options[:order] ||= :asc
       options[:what]  ||= :first
+      options[:delete_after_find] ||= false
       options
     end
   
-    # Start a POP3 session and ensures that it will be closed in any case.
-    def start(config = Mail::Configuration.instance, &block)
+    # Start a POP3 session and ensure that it will be closed in any case. Any messages
+    # marked for deletion via #find_and_delete or with the :delete_after_find option
+    # will be deleted when the session is closed.
+    def start(config = Configuration.instance, &block)
       raise ArgumentError.new("Mail::Retrievable#pop3_start takes a block") unless block_given?
     
       pop3 = Net::POP3.new(settings[:address], settings[:port], isapop = false)
@@ -150,10 +132,9 @@ module Mail
       yield pop3
     ensure
       if defined?(pop3) && pop3 && pop3.started?
-        pop3.reset # This clears all "deleted" marks from messages.
         pop3.finish
       end
     end
-  
+
   end
-end
+end

data/lib/mail/network/retriever_methods/test_retriever.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+
+module Mail
+
+  class TestRetriever < Retriever
+    cattr_accessor :emails
+
+    def initialize(values)
+      @@emails = []
+    end
+
+    def find(options = {}, &block)
+      options[:count] ||= :all
+      options[:order] ||= :asc
+      options[:what] ||= :first
+      emails = @@emails.dup
+      emails.reverse! if options[:what] == :last
+      emails = case count = options[:count]
+        when :all then emails
+        when 1 then emails.first
+        when Fixnum then emails[0, count]
+        else
+          raise 'Invalid count option value: ' + count.inspect
+      end
+      if options[:what] == :last && options[:order] == :asc || options[:what] == :first && options[:order] == :desc
+        emails.reverse!
+      end
+      emails.each { |email| email.mark_for_delete = true } if options[:delete_after_find]
+      if block_given?
+        emails.each { |email| yield email }
+      else
+        emails
+      end.tap do |results|
+        emails.each { |email| @@emails.delete(email) if email.is_marked_for_delete? } if options[:delete_after_find]
+      end
+    end
+
+  end
+
+end

data/lib/mail/network.rb

@@ -1,9 +1,13 @@
+require 'mail/network/retriever_methods/base'
+
 module Mail
   autoload :SMTP, 'mail/network/delivery_methods/smtp'
   autoload :FileDelivery, 'mail/network/delivery_methods/file_delivery'
   autoload :Sendmail, 'mail/network/delivery_methods/sendmail'
+  autoload :SMTPConnection, 'mail/network/delivery_methods/smtp_connection'
   autoload :TestMailer, 'mail/network/delivery_methods/test_mailer'
 
   autoload :POP3, 'mail/network/retriever_methods/pop3'
   autoload :IMAP, 'mail/network/retriever_methods/imap'
+  autoload :TestRetriever, 'mail/network/retriever_methods/test_retriever'
 end

data/lib/mail/parsers/address_lists.rb

@@ -13,7 +13,7 @@ module Mail
 
     module PrimaryAddress0
       def addresses
-        [first_addr] + other_addr.elements.map { |o| o.addr_value }
+        ([first_addr] + other_addr.elements.map { |o| o.addr_value }).reject { |e| e.empty? }
       end
     end
 
@@ -61,4 +61,4 @@ module Mail
     include AddressLists
   end
 
-end
+end

data/lib/mail/parsers/address_lists.treetop

@@ -6,7 +6,7 @@ module Mail
     rule primary_address
       address_list {
         def addresses
-          [first_addr] + other_addr.elements.map { |o| o.addr_value }
+          ([first_addr] + other_addr.elements.map { |o| o.addr_value }).reject { |e| e.empty? }
         end
       } / obs_addr_list {
         def addresses
@@ -16,4 +16,4 @@ module Mail
     end
     
   end
-end
+end