smailer 0.4.2 → 0.4.3

data/README.md

@@ -8,17 +8,19 @@ It is intended to be used within a Rails project. It has been tested with Rails
 
 ## Install
 
-### Install the Gem
+### Install the gem
 
-For Rails 3 projects, update your Gemfile and add:
+For Rails 3 projects, add the following to your `Gemfile`:
 
 	gem 'smailer'
 
-Then run `bundle install`. For Rails 2.x projects which do not use Bundler, add `config.gem 'smailer'` to your `environment.rb` file and then run `rake gems:install` in your project's root.
+Then run `bundle install`. For Rails 2.x projects which do not use Bundler, add `config.gem 'smailer'` to your `environment.rb` file and then run `rake gems:install` in your project's root. Also, if you use Rails 2.3.5, you may need to explicitly require a newer version of the `mail` gem, because `mail 2.2.x` has a dependency on ActiveSupport 2.3.6. For example, you can add this to your Rails 2.3.5's `environment.rb`:
+
+	config.gem 'mail', :version => '~> 2.3' # we need 2.3.x which does not depend on ActiveSupport 2.3.6
 
 ### Generate and run the migration
 
-To create the tables needed by Smailer to operate, run the `smailer:migration` generator after installing the Gem. For Rails 3, you can do this:
+To create the tables needed by Smailer to operate, run the `smailer:migration` generator after installing the gem. For Rails 3, you can do this:
 
 	rails g smailer:migration && bundle exec rake db:migrate
 
@@ -41,11 +43,11 @@ Sending out newsletters consists of a couple of steps:
 * At least one record should exist in `Smailer::Models::MailingList`. This record can then be used for unsubscribe requests if your system supports multiple newsletter types.
 * For each newsletter issue you intend to send, you should create a `Smailer::Models::MailCampaign` record. This record contains the subject and body contents of the newsletter you will be sending out.
 * Given a list of active subscribers your application provides, you then enqueue mails to be send via the `MailCampaign#queued_mails` list (see the example below).
-* Finally, you should call `Smailer::Tasks::Send.execute` repeatedly to process and send-out the enqueued emails.
+* Finally, you should call `Smailer::Tasks::Send.execute` repeatedly to process and send-out the enqueued emails, probably via a Cron daemon.
 
 ### Issuing a newsletter
 
-This is an example how you could proceed with creating and issuing a newsletter:
+Here is an example how you could proceed with creating and issuing a newsletter:
 
 	# locate the mailing list we'll be sending to
 	list = Smailer::Models::MailingList.first
@@ -75,7 +77,7 @@ This is an example how you could proceed with creating and issuing a newsletter:
 
 ### Managing unsubscriptions
 
-There are a few unsubscription methods supported. The most common one is probably via a unsubscribe link in the email. 
+Among the few unsubscription methods supported, probably the most widely used one is unsubscription via a unsubscribe link in the email. 
 
 In order to help you with implementing it, Smailer provides you with some interpolations you can use in the email's body:
 
@@ -89,9 +91,9 @@ In order to help you with implementing it, Smailer provides you with some interp
 Here is an example text you could include in the HTML version of your email to show a unsubscribe link (this also demonstrates how interpolation in the email's body works):
 
 	<p>If you wish to be removed from our mailinglist go here: <a href="http://yourcomain.com/unsubscribe/%{email_key}">http://yourcomain.com/unsubscribe/%{email_key}</a>.</p>
-	<p>You are subscribed to the list with the email address: %{escaped_email}</p>
+	<p>You are subscribed to the list with the following email address: %{escaped_email}</p>
 
-You have to implement a route in your Rails app to handle '/unsubscribe/:email_key'. For example, it could go to `UnsubscribeController#unsubscribe`, which you could implement like so:
+In this case, you will have to add a route in your Rails app to handle URLs like `'/unsubscribe/:email_key'`. For example, it could lead to `UnsubscribeController#unsubscribe`, which you could implement like so:
 
 	@email = Smailer::Models::MailKey.find_by_key(params[:email_key]).try(:email)
 	raise ActiveRecord::RecordNotFound unless @email
@@ -101,13 +103,13 @@ You have to implement a route in your Rails app to handle '/unsubscribe/:email_k
 
 ### Sending mails
 
-The emails which have been placed in the queue previously, have to be sent out at some point. This can be done for example with a Rake task which is run periodically via a Cron daemon. Here's an example Rake task:
+The emails which have already been placed in the send queue, have to be sent out at some point. This can be done for example with a Rake task which is run periodically via a Cron daemon. Here's an example Rake task you could use:
 
 	# lib/tasks/smailer.rake
 	namespace :smailer do
 	  desc 'Send out a batch of queued emails.'
 	  task :send_batch => :environment do
-	    result = Smailer::Tasks::Send.execute
+	    result = Smailer::Tasks::Send.execute :return_path_domain => 'bounces.mydomain.com', :verp => true
 	    result.each do |queue_item, status|
 	      puts "Sending #{queue_item.to}: #{status}"
 	    end
@@ -116,8 +118,13 @@ The emails which have been placed in the queue previously, have to be sent out a
 
 This task can be executed via `RAILS_ENV=production bundle exec rake smailer:send_batch` (provided you are running it on your production servers).
 
+Notice that we pass a `:return_path_domain` option to `Send.execute`. This domain will be used to construct a dynamic `Return-Path:` address, which you could later use in order to process bounced mails and connect the bounce with a concrete mail campaign and sender's email address. The generated return path will have the following format: `"bounces-SOMEKEY@bounces.mydomain.com"`, where `SOMEKEY` will be the same as the `key` field in the corresponding `FinishedMail` record and will uniquely identify this record, and `bounces.mydomain.com` is what you passed to `:return_path_domain`.
+
+Dynamic return path is generated only when `:return_path_domain` is specified and `:verp` is not false. If you omit the `:verp` option and just pass `:return_path_domain`, `Send.execute` will still use VERP and generate dynamic return path addresses.
+
 ## TODO
 
+* Bounce processing
 * Tests, tests, tests
 
 ## Contribution

data/lib/smailer/models/queued_mail.rb

@@ -38,6 +38,8 @@ module Smailer
       end
 
       def interpolate(text)
+        return text if text.nil?
+
         {
           :email            => to,
           :escaped_email    => lambda { ERB::Util.h(to) },

data/lib/smailer/version.rb

@@ -1,3 +1,3 @@
 module Smailer
-  VERSION = "0.4.2"
+  VERSION = "0.4.3"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: smailer
 version: !ruby/object:Gem::Version 
-  hash: 11
+  hash: 9
   prerelease: 
   segments: 
   - 0
   - 4
-  - 2
-  version: 0.4.2
+  - 3
+  version: 0.4.3
 platform: ruby
 authors: 
 - Dimitar Dimitrov
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-28 00:00:00 +03:00
+date: 2011-10-06 00:00:00 +03:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency