fast-mailer 0.0.1

data/LICENCE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Erik Hansson
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,70 @@
+FastMailer
+==========
+
+FastMailer is a collection of helpers that aims to help with sending email.
+Specifically, it allows for convenient configuration and better throughput
+when sending multiple mails.
+
+
+Configuration
+-------------
+
+The FastMailer senders are configured with a regular options hash, pretty 
+much what you'd expect:
+
+    FastMailer::SMTP.new({
+      :host => 'mail.authsmtp.com',
+      :port => 2525,
+      :authentication => :cram_md5,
+      :domain => 'mydomain.com',
+      :username => 'username',
+      :password  => 'password'
+    })
+
+Something I've found very convenient, however, is to let the gem read the
+default configuration from your home directory. For instance, let's assume
+we put:
+
+    {
+      :host => 'mail.authsmtp.com',
+      :port => 2525,
+      :authentication => :cram_md5,
+      :domain => 'mydomain.com',
+      :username => 'username',
+      :password  => 'password'
+    }
+    
+into **~/.config/smtp.rb**, you could then achieve the same result by simply
+not providing any options at all. This makes it really easy to write small 
+scripts that send email without having to worry about configuration.
+
+
+Sending mail
+------------
+
+When sending a lot of mail, every second counts - especially if you don't
+have your SMTP server close by. To reduce the time it takes to send a lot of
+email, we can send multiple emails using a single connection.
+
+    mail = build_mail_somehow # mail is a Mail instance (as from the mail gem)
+    
+    FastMailer::SMTP.new.open do |smtp|
+      smtp.deliver mail
+      mail.to = 'another@recipient.com'
+      smtp.deliver mail
+    end
+
+
+Coming features
+---------------
+
+* Parallelisation: given a list of mails, or a mail generator, we can spin a number
+of threads up and let them send mail simultaneously. As most of the time is spent
+waiting for the network, this speeds the process up significantly.
+
+* Logging: When sending large batches, sometimes things go wrong. If we keep track 
+of which mails have been sent and which have failed, we reduce the risk of finding
+ourselves wondering which of our users have received the message and which we need
+to send to.
+
+* Blacklisting: block addresses so they cannot be sent to.

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/fast-mailer.rb

@@ -0,0 +1,5 @@
+
+require 'mail'
+
+require 'fast-mailer/configuration'
+require 'fast-mailer/smtp'

data/lib/fast-mailer/configuration.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+
+module FastMailer
+  class Configuration
+    
+    TEST_CONFIGURATION = {
+      :something => :useful
+    }
+    
+    def self.enable_testing!
+      def self.smtp_configuration(options = nil)
+        TEST_CONFIGURATION
+      end
+    end
+    
+    def self.disable_testing!
+      def self.smtp_configuration(options = nil)
+        if options.is_a? Hash
+          options
+        else
+          eval(File.read(options || File.expand_path("~/.config/smtp.rb")))
+        end
+      end
+    end
+    
+    disable_testing!
+    
+  end
+end

data/lib/fast-mailer/smtp.rb

@@ -0,0 +1,79 @@
+
+module FastMailer
+  
+  # Sends messages using an SMTP server. The SMTP options is passed through
+  # FastMailer::Configuration, so you can set your system up to automatically
+  # use your SMTP configuration. Also, FastMailer::SMTP supports that you send
+  # multiple emails over a single connection, allowing for faster delivery
+  # of multiple emails.
+  #
+  # Note that if an error is raised by Net::SMTP, the connection may not be
+  # reliable. As a best practice, always discard the current connection and
+  # reopen a new one in case you encounter an error. Do not attempt to continue
+  # sending mail on the same connection.
+  class SMTP
+    
+    attr_accessor :configuration
+    
+    def initialize(options = nil)
+      @configuration = FastMailer::Configuration.smtp_configuration options
+    end
+    
+    def open
+      @opened = true
+
+      configuration[:host] ||= configuration[:address]
+      configuration[:username] ||= configuration[:user_name]
+      
+      @smtp = Net::SMTP.new(configuration[:host], configuration[:port])
+      if configuration[:enable_starttls_auto]
+        smtp.enable_starttls_auto if smtp.respond_to?(:enable_starttls_auto) 
+      end
+      
+      @smtp.start(configuration[:domain], configuration[:username], configuration[:password], configuration[:authentication]) do |smtp|
+        yield self
+      end
+    ensure
+      @smtp = nil
+      @opened = false
+    end
+    
+    def deliver(mail)
+      if @opened
+        perform_delivery(mail)
+      else
+        open do
+          deliver mail
+        end
+      end
+    end
+    
+    private
+    def perform_delivery(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
+      
+      begin
+        @smtp.sendmail(message, envelope_from, destinations)
+      rescue e
+        @smtp = nil
+        raise e
+      end
+    end
+    
+  end
+end

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification 
+name: fast-mailer
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Erik Hansson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-29 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mail
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 2
+        - 5
+        version: 2.2.5
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: i18n
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 0
+        - 0
+        - beta
+        - 22
+        version: 2.0.0.beta.22
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 8
+        - 7
+        version: 0.8.7
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: autotest
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id006
+description: Helps with sending emails fast, and with convenient configuration.
+email: 
+- erik@bits2life.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/fast-mailer/configuration.rb
+- lib/fast-mailer/smtp.rb
+- lib/fast-mailer.rb
+- LICENCE
+- VERSION
+- README.md
+has_rdoc: true
+homepage: http://github.com/erikhansson/fast-mailer
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: nowarning
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Help with sending emails.
+test_files: []
+