simpleemail

Object

== 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. ======examples/email_settings_sendmail.rb: ActionMailer::Base.delivery_method = :sendmail

This script sends a basic email to two receivers via sendmail. ======examples/email_results_1.rb: #!/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. ======examples/email_settings_smtp.rb: 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 = '[e-mail]' SimpleEmail::Email.default_to = '[e-mail]'

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. ======examples/email_results_2.rb: #!/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

[ActionMailer::Base.smtp_settings[:tls]] Whether tls will be enabled. Possible values are :always, :never, :auto. If :auto is specified, tls will be enabled if the smtp server offers tls AND the version of ruby is such that the net/smtp library supports tls. If not specified, this setting will default to :auto.

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).

• SimpleEmail::Email.default_from - Optional - The default from address.
• SimpleEmail::Email.default_to - 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-2009 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!