simpleemail 1.0.0

data/History.txt

@@ -0,0 +1,3 @@
+=== 1.0.0 / 2008-08-05
+Initial release of SimpleEmail.
+

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Designing Patterns
+
+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/Manifest.txt

@@ -0,0 +1,10 @@
+Manifest.txt
+LICENSE
+History.txt
+README.txt
+Rakefile
+lib/simpleemail.rb
+lib/simpleemail/action_mailer_ssl.rb
+lib/simpleemail/email.rb
+test/emailsettings.rb
+test/test_simpleemail.rb

data/README.txt

@@ -0,0 +1,173 @@
+= simpleemail
+* Project Page: http://rubyforge.org/projects/simpleemail/
+* Documentation: http://simpleemail.rubyforge.org/
+
+== DESCRIPTION:
+
+This package simplifies sending emails outside of the Rails
+environment.  It is a wrapper around the ActionMailer package.
+Support for smtp over tls is included if you are using Ruby 1.8.7 or
+above.  The API provided is very bare, but can be easily extended.
+The email configuration is provided through a user-specified
+configuration file (identical to the ActionMailer configuration in
+environment.rb in Rails except for the added tls option).  This
+package is most useful in the situation that a user has a number of
+scripts (outside of the Rails environment) that all send very basic
+emails (to, from, body, subject).
+
+== PROBLEMS:
+
+None (known).
+
+== SYNOPSIS:
+
+Lets walk through some example invocations of the library.
+
+Here is an example configuration file that specifies sendmail as the delivery method.
+======<tt>examples/email_settings_sendmail.rb</tt>:
+ ActionMailer::Base.delivery_method = :sendmail
+
+
+This script sends a basic email to two receivers via sendmail.
+======<tt>examples/email_results_1.rb</tt>:
+ #!/usr/bin/env ruby
+ 
+ require 'rubygems'
+ require 'simpleemail'
+ 
+ 
+ SimpleEmail::Email.email_settings_file = "email_settings_sendmail.rb"
+ 
+ subject = "Re: This is a test!"
+ body = "..."
+ 
+ SimpleEmail::Email.send_email("tony", 
+                               "janet, tony",
+                               subject, 
+                               body)
+ 
+
+
+Here is an example configuration file that specifies smtp as the delivery method.
+======<tt>examples/email_settings_smtp.rb</tt>:
+ ActionMailer::Base.delivery_method = :smtp
+ 
+ ActionMailer::Base.smtp_settings = {
+   :address => 'smtp.gmail.com',
+   :port   => 587,
+   :domain => "gmail.com",
+   :authentication => "login",
+   :user_name => "sender",
+   :password => "zepassword",
+   :tls => :auto
+ }
+ 
+ SimpleEmail::Email.default_from = 'sender@gmail.com'
+ SimpleEmail::Email.default_to = 'receiver@gmail.com'
+ 
+
+
+This script sends a basic email via smtp with tls to be enabled if the
+smtp server supports it.  The default to and from fields from the
+configuration file are used.
+======<tt>examples/email_results_2.rb</tt>:
+ #!/usr/bin/env ruby
+ 
+ require 'rubygems'
+ require 'simpleemail'
+ 
+ 
+ SimpleEmail::Email.email_settings_file = "email_settings_smtp.rb"
+ 
+ subject = "Re: This is a test!"
+ body = "..."
+ 
+ SimpleEmail::Email.send_email(nil, nil, subject, body)
+
+
+== CONFIGURATION FILE:
+
+The configuration file allows the user to configure the
+ActionMailer::Base class, in the same fashion that it is configured in
+environment.rb in the Rails environment.  This library includes one
+additional option
+
+[<tt>ActionMailer::Base.smtp_settings[:tls]</tt>]
+    Whether tls will be enabled.  Possible values are <tt>:always,
+    :never, :auto</tt>.  If <tt>:auto</tt> is specified, tls will be
+    enabled if the smtp server offers tls AND the version of ruby is
+    such that the <tt>net/smtp</tt> library supports tls.  If not
+    specified, this setting will default to <tt>:auto</tt>.
+
+The tls option will only work with Ruby version 1.8.7 and above.  This
+is due to changes to the ruby standard library (as of 1.8.7) to
+include tls support in the net/smtp library.  For a detailed
+explanation of the ActionMailer configuration, see the {Rails
+ActionMailer
+documentation}[http://api.rubyonrails.org/classes/ActionMailer/Base.html]
+in the {Ruby On Rails API}[http://api.rubyonrails.org].
+
+The configuration file also allows the user to specify a default from
+email address and default to email address(es).
+* <tt>SimpleEmail::Email.default_from</tt> - Optional - The default from address.
+* <tt>SimpleEmail::Email.default_to</tt> - Optional - The default to address(es).
+ 
+The user can also specify the to/from fields as parameters in each
+call to SimpleEmail::Email.send_email.  If specified (the parameters
+passed are non-nil), they will override the default to/from fields.
+
+== REQUIREMENTS:
+
+This package requires actionmailer, hoe, and relative.  Hoe and
+relative are required only for running the tests.
+
+== INSTALL:
+
+ sudo gem install simpleemail
+
+== AUTHORS:
+=== Designing Patterns
+* Homepage: http://www.designingpatterns.com
+* Blogs: http://blogs.designingpatterns.com
+
+== SUPPORT:
+Please post questions, concerns, or requests for enhancement to the forums on
+the project page.  Alternatively, direct contact information for
+Designing Patterns can be found on the project page for this gem.
+
+== ENHANCEMENTS:
+Please feel free to contact us with any ideas; we will try our best to
+enhance the software and respond to user requests.  Of course, we are more
+likely to work on a particular enhancement if we know that there are users
+who want it.  Designing Patterns provides contracting and consulting services,
+so if there is an enhancement that *must* get done (and in a specified time
+frame), please inquire about retaining our services!
+
+== LICENSE:
+The license text can be found in the +LICENSE+ file at the root of the
+distribution.
+
+This  package is licensed with an MIT license:
+
+Copyright (c) 2008 Designing Patterns
+
+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.
+
+== SHARE AND ENJOY!

data/Rakefile

@@ -0,0 +1,13 @@
+# -*- ruby -*-
+require 'rubygems'
+require 'hoe'
+
+Hoe.new('simpleemail', "1.0.0") do |p|
+  p.remote_rdoc_dir = ''
+  p.developer('DesigningPatterns', 'technical.inquiries@designingpatterns.com')
+
+  p.extra_deps << ['actionmailer']
+  p.extra_deps << ['relative']
+end
+
+# vim: syntax=Ruby

data/lib/simpleemail.rb

@@ -0,0 +1,2 @@
+#!/usr/bin/env ruby
+require 'simpleemail/email'

data/lib/simpleemail/action_mailer_ssl.rb

@@ -0,0 +1,58 @@
+require 'rubygems'
+require 'action_mailer'
+
+#
+# This file enhances the ActionMailer::Base class's smtp code to read
+# a new ActionMailer::Base.smtp_settings configuration parameter (tls)
+# and enable tls on the smtp connection based on this parameter.
+#
+
+module ActionMailer #:nodoc:
+
+  class Base
+
+    undef perform_delivery_smtp
+
+    def perform_delivery_smtp(mail)
+      destinations = mail.destinations
+      mail.ready_to_send
+      sender = mail['return-path'] || mail.from
+      
+      smtp = Net::SMTP.new(smtp_settings[:address], smtp_settings[:port])
+      
+      if (logger && logger.level <= Logger::DEBUG)
+        smtp.debug_output = logger
+      end
+      
+      # The tls methods should be available in the net/smtp library
+      # for ruby 1.8.7 and above.
+      case smtp_settings[:tls]
+      when :always
+        smtp.enable_starttls()
+      when :auto
+        smtp.enable_starttls_auto()
+      when nil
+        # if no tls setting was specified and the net/smtp library
+        # supports tls, enable tls to automatically be enabled if the
+        # smtp server supports it.
+        if (smtp.respond_to?(:enable_starttls_auto))
+          smtp.enable_starttls_auto()
+        end
+      when :never
+      else
+        raise Exception "Unexpected value for smtp setting (tls): Available values: (:always, :auto, :never)"
+      end
+      
+      begin
+        smtp.start(smtp_settings[:domain], smtp_settings[:user_name], 
+                   smtp_settings[:password], smtp_settings[:authentication])
+        
+        smtp.sendmail(mail.encoded, sender, destinations)
+      ensure
+        if (smtp.started?()) then smtp.finish() end
+      end
+      
+    end
+  end
+  
+end

data/lib/simpleemail/email.rb

@@ -0,0 +1,85 @@
+require 'simpleemail/action_mailer_ssl'
+
+module SimpleEmail
+
+  # This class provides basic email functionality.  It is a wrapper
+  # around the ActionMailer package.
+  class Email
+    @@email_settings_file = nil
+    @@default_to = nil
+    @@default_from = nil
+    
+    class << self
+      undef_method :new
+    end
+    
+    def self.email_settings_file(email_settings_file)
+      @@email_settings_file
+    end
+    
+    def self.email_settings_file=(email_settings_file)
+      @@email_settings_file = email_settings_file
+
+      eval(IO.read(@@email_settings_file))
+      
+      # Warn the user if they're specifying the tls smtp setting and
+      # their ruby version does not support this.
+      if ((ActionMailer::Base.smtp_settings['tls'] == :always || ActionMailer::Base.smtp_settings['tls'] == :auto) && 
+          RUBY_VERSION < "1.8.7" &&
+          logger = ActionMalier::Base.logger)
+        logger.warn("Tls is not supported by the net/smtp library for versions earlier than 1.8.7.")
+      end
+    end
+    
+    def self.default_to()
+      @@default_to
+    end
+    
+    def self.default_to=(default_to)
+      @@default_to = default_to
+    end
+    
+    def self.default_from()
+      @@default_from
+    end
+    
+    def self.default_from=(default_from)
+      @@default_from = default_from
+    end
+    
+    #
+    # ====Description:
+    # This method sends an email to the specified to address.
+    # 
+    # ====Parameters:
+    # [from]
+    #      The from address.  If this parameter's value is nil and a
+    #      default from address was specified, the default from
+    #      address will be used.
+    # [to]
+    #      The to address.  If this parameter's value is nil and a
+    #      default to address was specified, the default to address
+    #      will be used.
+    #
+    def self.send_email(from, to, subject, body)
+      if !from then from = @@default_from end
+      if !to then to = @@default_to end
+
+      GeneralMailer.deliver_simple_email(from, to, subject, body)
+    end
+  end
+
+  class GeneralMailer < ActionMailer::Base #:nodoc:
+    
+    def simple_email(the_sender, the_recipients, the_subject, the_body)
+      recipients(the_recipients)
+      from(the_sender)
+      subject(the_subject)
+      
+      #setting the body explicitly means we don't have to provide a
+      #separate template file
+      body(the_body)
+    end  
+  end
+end
+

data/test/emailsettings.rb

@@ -0,0 +1,15 @@
+ActionMailer::Base.delivery_method = :smtp
+
+ActionMailer::Base.smtp_settings = {
+  :address => 'smtp.gmail.com',
+  :port   => 587,
+  :domain => "gmail.com",
+  :authentication => "login",
+  :user_name => "sender",
+  :password => "zepassword",
+  :tls => :auto
+}
+
+SimpleEmail::Email.default_from = 'sender@gmail.com'
+SimpleEmail::Email.default_to = 'receiver@gmail.com'
+

data/test/test_simpleemail.rb

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+
+require 'simpleemail'
+
+require 'rubygems'
+require 'relative'
+
+require 'test/unit'
+
+class TestSimpleEmail < Test::Unit::TestCase
+
+  def test_email()
+    send_and_verify()
+
+    from = "override_sender@gmail.com"
+    to = "override_receiver1@gmail.com, override_receiver2@gmail.com"
+    send_and_verify(from, to)
+  end
+
+  def send_and_verify(from = nil, to = nil)
+    SimpleEmail::Email.email_settings_file = 
+      Pathname.new("emailsettings.rb").expand_path_relative_to_caller()
+
+    ActionMailer::Base.delivery_method = :test
+    ActionMailer::Base.deliveries = []
+    
+    subject = "Subject"
+    body =  "Testing\n"
+    body << "1\n"
+    body << "2\n"
+    body << "3\n"
+    
+    SimpleEmail::Email.send_email(from, to, subject, body)
+    
+    deliveries = ActionMailer::Base.deliveries
+    assert_equal(deliveries.length, 1)
+    
+    delivery = deliveries[0]
+    assert_equal(delivery.subject, subject)
+    assert_equal(delivery.body, body)
+
+    actual_to = (to ? to : SimpleEmail::Email.default_to).split(/, +/)
+    actual_from = (from ? from : SimpleEmail::Email.default_from).split(/, +/)
+    
+    assert_equal(delivery.to, actual_to)
+    assert_equal(delivery.from, actual_from)
+    
+
+  end 
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification 
+name: simpleemail
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- DesigningPatterns
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-08-05 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: actionmailer
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: relative
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.7.0
+    version: 
+description: This package simplifies sending emails outside of the Rails environment.  It is a wrapper around the ActionMailer package. Support for smtp over tls is included if you are using Ruby 1.8.7 or above.  The API provided is very bare, but can be easily extended. The email configuration is provided through a user-specified configuration file (identical to the ActionMailer configuration in environment.rb in Rails except for the added tls option).  This package is most useful in the situation that a user has a number of scripts (outside of the Rails environment) that all send very basic emails (to, from, body, subject).
+email: 
+- technical.inquiries@designingpatterns.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- Manifest.txt
+- History.txt
+- README.txt
+files: 
+- Manifest.txt
+- LICENSE
+- History.txt
+- README.txt
+- Rakefile
+- lib/simpleemail.rb
+- lib/simpleemail/action_mailer_ssl.rb
+- lib/simpleemail/email.rb
+- test/emailsettings.rb
+- test/test_simpleemail.rb
+has_rdoc: true
+homepage: "Project Page: http://rubyforge.org/projects/simpleemail/"
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: simpleemail
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: This package simplifies sending emails outside of the Rails environment
+test_files: 
+- test/test_simpleemail.rb