mail 1.6.0 → 2.0.3

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

@@ -1,17 +1,39 @@
 module Mail
+  
+  # FileDelivery class delivers emails into multiple files based on the destination
+  # address.  Each file is appended to if it already exists.
+  # 
+  # So if you have an email going to fred@test, bob@test, joe@anothertest, and you
+  # set your location path to ~/tmp/mails then FileDelivery will create ~/tmp/mails
+  # if it does not exist, and put one copy of the email in three files, called
+  # "fred@test", "bob@test" and "joe@anothertest"
+  # 
+  # Make sure the path you specify with :location is writable by the Ruby process
+  # running Mail.
   class FileDelivery
-    include Singleton
-    
-    def settings(&block)
-      if block_given?
-        instance_eval(&block)
-      end
-      self
+
+    if RUBY_VERSION >= '1.9.1'
+      require 'fileutils'
+    else
+      require 'ftools'
+    end
+
+    def initialize(values)
+      self.settings = { :location => './mails' }.merge!(values)
     end
     
-    def FileDelivery.deliver!(mail)
-      # To be implemented
-      Mail.deliveries << mail
+    attr_accessor :settings
+    
+    def deliver!(mail)
+      if ::File.respond_to?(:makedirs)
+        ::File.makedirs settings[:location]
+      else
+        ::FileUtils.mkdir_p settings[:location]
+      end
+
+      mail.destinations.uniq.each do |to|
+        ::File.open(::File.join(settings[:location], to), 'a') { |f| "#{f.write(mail.encoded)}\r\n\r\n" }
+      end
     end
     
   end

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

@@ -1,22 +1,60 @@
 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
-    include Singleton
-
-    def settings(&block)
-      if block_given?
-        instance_eval(&block)
-      end
-      self
+    
+    def initialize(values)
+      self.settings = { :location       => '/usr/sbin/sendmail',
+                        :arguments      => '-i -t' }.merge(values)
     end
+    
+    attr_accessor :settings
 
-    def path(value = nil)
-      value ? @path = value : @path
-    end
+    def deliver!(mail)
+      envelope_from = mail.return_path || mail.sender || mail.from_addrs.first
+      return_path = "-f \"#{envelope_from}\"" if envelope_from
 
-    def Sendmail.deliver!(mail)
-      mail.return_path ? return_path = "-f \"#{mail.return_path}\"" : reply_to = ''
-      IO.popen("#{Mail.defaults.sendmail.path} #{return_path} #{mail.destinations.join(" ")}", "w+") do |io|
-        io.puts mail.to_s
+      arguments = [settings[:arguments], return_path].compact.join(" ")
+      
+      Sendmail.call(settings[:location], arguments, mail.destinations.join(" "), mail)
+    end
+    
+    def Sendmail.call(path, arguments, destinations, mail)
+      IO.popen("#{path} #{arguments} #{destinations}", "w+") do |io|
+        io.puts mail.encoded.to_lf
         io.flush
       end
     end

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

@@ -1,87 +1,104 @@
 module Mail
+  # == Sending Email with SMTP
+  # 
+  # Mail allows you to send emails using SMTP.  This is done by wrapping Net::SMTP in
+  # an easy to use manner.
+  # 
+  # === Sending via SMTP server on Localhost
+  # 
+  # Sending locally (to a postfix or sendmail server running on localhost) requires
+  # no special setup.  Just to Mail.deliver &block or message.deliver! and it will
+  # be sent in this method.
+  # 
+  # === Sending via MobileMe
+  # 
+  #   Mail.defaults do
+  #     delivery_method :smtp, { :address              => "smtp.me.com",
+  #                              :port                 => 587,
+  #                              :domain               => 'your.host.name',
+  #                              :user_name            => '<username>',
+  #                              :password             => '<password>',
+  #                              :authentication       => 'plain',
+  #                              :enable_starttls_auto => true  }
+  #   end
+  # 
+  # === Sending via GMail
+  # 
+  #   Mail.defaults do
+  #     delivery_method :smtp, { :address              => "smtp.gmail.com",
+  #                              :port                 => 587,
+  #                              :domain               => 'baci.lindsaar.net',
+  #                              :user_name            => 'raasdnil',
+  #                              :password             => 'g333ma11',
+  #                              :authentication       => 'plain',
+  #                              :enable_starttls_auto => true  }
+  #   end
+  #
+  # === Others 
+  # 
+  # Feel free to send me other examples that were tricky
+  # 
+  # === Delivering the email
+  # 
+  # Once you have the settings right, sending the email is done by:
+  # 
+  #   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 SMTP
-    include Singleton
-    
-    def initialize
-      @user = nil
-      @pass = nil
-      @tls  = false
-    end
-    
-    def settings(&block)
-      if block_given?
-        instance_eval(&block)
-      end
-      self
-    end
-    
-    # This is the host that you will send your SMTP mails to, defaults to 'localhost'
-    def host(value = nil)
-      value ? @host = value : @host ||= 'localhost'
-    end
 
-    # This is the port that SMTP email get sent to, default is 25
-    def port(value = nil)
-      value ? @port = value.to_i : @port ||= 25
-    end
-    
-    # The username to use during SMTP authentication
-    def user(value = nil)
-      value ? @user = value : @user
+    def initialize(values)
+      self.settings = { :address              => "localhost",
+                        :port                 => 25,
+                        :domain               => 'localhost.localdomain',
+                        :user_name            => nil,
+                        :password             => nil,
+                        :authentication       => nil,
+                        :enable_starttls_auto => true  }.merge!(values)
     end
     
-    # Password to use during SMTP authentication
-    def pass(value = nil)
-      value ? @pass = value : @pass
-    end
-    
-    # The helo domain used at the begining of an SMTP conversation,
-    # default is 'localhost.localdomain'
-    def helo(value = nil)
-      value ? @helo = value : @helo ||= 'localhost.localdomain'
-    end
-    
-    # Turn on TLS
-    def enable_tls
-      @tls = true
-    end
-    
-    # Turn off TLS
-    def disable_tls
-      @tls = false
-    end
-    
-    # TLS Enabled?  Default is false
-    def tls?
-      @tls || false
-    end
+    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 SMTP.deliver!(mail)
-      
-      config = Mail.defaults
+    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
-      raise ArgumentError.new('An sender (Return-Path, Sender or From) required to send a message') if envelope_from.blank?
+      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
-      raise ArgumentError.new('At least one recipient (To, Cc or Bcc) is required to send a message') if destinations.blank?
+      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)
-      raise ArgumentError.new('A encoded content is required to send a message') if message.blank?
+      if message.blank?
+        raise ArgumentError.new('A encoded content is required to send a message')
+      end
       
-      smtp = Net::SMTP.new(config.smtp.host, config.smtp.port)
-      if config.smtp.tls?
-        if OpenSSL::SSL::VERIFY_NONE.kind_of?(OpenSSL::SSL::SSLContext)
-          smtp.enable_tls(OpenSSL::SSL::VERIFY_NONE)
-        else
-          smtp.enable_tls
-        end
-      else
-        smtp.enable_starttls_auto if smtp.respond_to?(:enable_starttls_auto)
+      smtp = Net::SMTP.new(settings[:address], settings[:port])
+      if settings[:enable_starttls_auto]
+        smtp.enable_starttls_auto if smtp.respond_to?(:enable_starttls_auto) 
       end
       
-      smtp.start(config.smtp.helo, config.smtp.user, config.smtp.pass, authentication = :plain) do |smtp|
+      smtp.start(settings[:domain], settings[:user_name], settings[:password], settings[:authentication]) do |smtp|
         smtp.sendmail(message, envelope_from, destinations)
       end
       

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

@@ -1,14 +1,19 @@
 module Mail
   class TestMailer
-    include Singleton
+
+    def initialize(values)
+      @settings = {}
+    end
     
+    attr_accessor :settings
+
     # The Test Mailer provides a mail delivery method that does not hit
     # your network or mail agent, in this way you can send all the emails
     # you want and they will just be appended to Mail.deliveries
     # 
     # See the README under Using Mail with Testing or Spec'ing Libraries
     # for more information.
-    def TestMailer.deliver!(mail)
+    def deliver!(mail)
       Mail.deliveries << mail
     end
     

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

@@ -1,12 +1,13 @@
 module Mail
   class IMAP
-    include Singleton
     
-    def settings(&block)
-      if block_given?
-        instance_eval(&block)
-      end
-      self
+    def initialize(values)
+      self.settings = { :address              => "localhost",
+                        :port                 => 110,
+                        :user_name            => nil,
+                        :password             => nil,
+                        :authentication       => nil,
+                        :enable_ssl           => false }.merge!(values)
     end
     
     def IMAP.get_messages(&block)

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

@@ -1,65 +1,49 @@
 # encoding: utf-8
 
-# The Pop3 retriever allows to get the last, first or all emails from a Pop3 server.
-# Each email retrieved (RFC2822) is given as an instance of +Message+.
-#
-# While being retrieved, emails can be yielded if a block is given.
-#
-# This module uses the defaults set in Configuration to retrieve POP3 settings.
-# 
 module Mail
+  # The Pop3 retriever allows to get the last, first or all emails from a POP3 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 :pop3, { :address             => "pop.gmail.com",
+  #                               :port                => 995,
+  #                               :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 pop mailbox
+  # with the following 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.
+  # 
+  #   Mail.find(:what => :first, :count => 10, :order => :asc)
+  #   #=> Returns the first 10 emails in ascending order
+  # 
   class POP3
-    include Singleton
-    
-    def initialize
-      @user = nil
-      @pass = nil
-      @tls  = false
-    end
-    
     require 'net/pop'
-    
-    def settings(&block)
-      if block_given?
-        instance_eval(&block)
-      end
-      self
-    end
-    
-    # This is the host that you will send your POP3 mails to, defaults to 'localhost'
-    def host(value = nil)
-      value ? @host = value : @host ||= 'localhost'
-    end
 
-    # This is the port that POP3 email get sent to, default is 110
-    def port(value = nil)
-      value ? @port = value.to_i : @port ||= 110
-    end
-    
-    # The username to use during POP3 authentication
-    def user(value = nil)
-      value ? @user = value : @user
+    def initialize(values)
+      self.settings = { :address              => "localhost",
+                        :port                 => 110,
+                        :user_name            => nil,
+                        :password             => nil,
+                        :authentication       => nil,
+                        :enable_ssl           => false }.merge!(values)
     end
     
-    # Password to use during POP3 authentication
-    def pass(value = nil)
-      value ? @pass = value : @pass
-    end
-    
-    # Turn on TLS
-    def enable_tls
-      @tls = true
-    end
-    
-    # Turn on TLS
-    def disable_tls
-      @tls = false
-    end
-    
-    # TLS Enabled?  Default is false
-    def tls?
-      @tls || false
-    end
+    attr_accessor :settings
     
     # Get the oldest received email(s)
     #
@@ -67,7 +51,7 @@ module Mail
     #   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 POP3.first(options = {}, &block)
+    def first(options = {}, &block)
       options ||= {}
       options[:what] = :first
       options[:count] ||= 1
@@ -80,7 +64,7 @@ module Mail
     #   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 POP3.last(options = {}, &block)
+    def last(options = {}, &block)
       options ||= {}
       options[:what] = :last
       options[:count] ||= 1
@@ -92,7 +76,7 @@ module Mail
     # Possible options:
     #   order: order of emails returned. Possible values are :asc or :desc. Default value is :asc.
     #
-    def POP3.all(options = {}, &block)
+    def all(options = {}, &block)
       options ||= {}
       options[:count] = :all
       find(options, &block)
@@ -106,8 +90,7 @@ module Mail
     #   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.
     #
-    def POP3.find(options = {}, &block)
-      validate_configuration
+    def find(options = {}, &block)
       options = validate_options(options)
       
       start do |pop3|
@@ -136,31 +119,23 @@ module Mail
     end
     
   private
-    
-    # Ensure that the POP3 configuration is set
-    def POP3.validate_configuration
-      config = Mail::Configuration.instance
-      if config.pop3.host.blank? || config.pop3.port.blank?
-        raise ArgumentError.new('Please call +Mail.defaults+ to set the POP3 configuration')
-      end
-    end
   
     # Set default options
-    def POP3.validate_options(options)
+    def validate_options(options)
       options ||= {}
       options[:count] ||= 10
       options[:order] ||= :asc
-      options[:what] ||= :first
+      options[:what]  ||= :first
       options
     end
   
     # Start a POP3 session and ensures that it will be closed in any case.
-    def POP3.start(config = Mail::Configuration.instance, &block)
+    def start(config = Mail::Configuration.instance, &block)
       raise ArgumentError.new("Mail::Retrievable#pop3_start takes a block") unless block_given?
     
-      pop3 = Net::POP3.new(config.pop3.host, config.pop3.port, isapop = false)
-      pop3.enable_ssl(verify = OpenSSL::SSL::VERIFY_NONE) if config.pop3.tls?
-      pop3.start(config.pop3.user, config.pop3.pass)
+      pop3 = Net::POP3.new(settings[:address], settings[:port], isapop = false)
+      pop3.enable_ssl(verify = OpenSSL::SSL::VERIFY_NONE) if settings[:enable_ssl]
+      pop3.start(settings[:user_name], settings[:password])
     
       yield pop3
     ensure