smailer 0.7.8 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b00f6f0078ba4571bbecdb885793210b687dfe78
-  data.tar.gz: 43dbfab21a6a0df33fdc6888af15284b77098db7
+  metadata.gz: d2e3772412ea4ae474b3e81fdb40a1b283b4c483
+  data.tar.gz: 8c99e9cb73c3c259d97127c0c8f612eb8e779dab
 SHA512:
-  metadata.gz: 404447a9f14b07b2524b1cec4d76e455244df0418a927dce01b83e8097808e806281b01e941523ab9f1400d04a5bd97f6bb59d2d71ff039a4d1f9d3ddee248b6
-  data.tar.gz: e1b13572bab33e5053ebc377d302f37f85ec70584d220791b452609eeae78e5e81b65589f76891e87671579cf753d0d8da258d89e413dcb178a75ac800c643d6
+  metadata.gz: c65340fc1022af2ddcd1b21d71f4246fea5eef4ac4981f13c7a971889cce38709226acff5d293620fd1b328bffc2b35eedfec188ea80bcf661f8731fb9f012b3
+  data.tar.gz: 3790bc6d1bf551eb588cec59da2ae1b00969780e3609550b2b7e9570e8824db185884d4a79412d66b43e74e834eb5b37c042ae0da874bb5761b780eef7f04567

data/.gitignore

@@ -5,3 +5,7 @@ pkg/*
 .DS_Store
 *.sublime-*
 spec/dummy/log/*
+spec/dummy/db/development.sqlite3
+spec/dummy/db/migrate/*
+spec/dummy/db/test.sqlite3
+spec/dummy/db/schema.rb

data/CHANGELOG.md

@@ -0,0 +1,202 @@
+## Version v0.8.0
+
+- Adds support for one-off emails to be send via the same queueing mechanism.
+- It is now possible to disable the uniqueness validation for a single email
+  per recipient per campaign by passing `:require_uniqueness => false` when
+  creating a `QueuedMail` record.
+
+**Possible breaking changes:**
+
+- The `MailCampaignAttachment` chass is now called `MailAttachment`.
+- The interface to add an attachment has changed.
+
+    Attachments are no longer saved by `add_attachment`. You have to call
+    `Smailer::Models::MailCampaign#save` or `Smailer::Models::MailQueue#save`
+    (if it is one-off email).
+
+- There have been changes to the database structure.
+- The message key stored in `QueuedMail#key` is no longer generated based only
+  on predictable input. Now a `SecureRandom`-generated value is alos used.
+
+**Upgrading from v0.7.3 to v0.8.0**
+
+To make the required changes in the database, you can use this
+[smailer_v0_7_3_to_v0_8_0 migration](upgrading/migrations/smailer_v0_7_3_to_v0_8_0.rb).
+You may need to alter this migration to fit your data.
+**Don't just run it blindly**.
+
+## Version v0.7.8 (Feb 11 2015)
+
+Make sure QueuedMail is deleted
+
+## Version v0.7.7 (Feb 9 2015)
+
+Fix Rails 2.x compatibility
+
+## Version v0.7.5 (Dec 20 2014)
+
+Fix send task when no mail config is present
+
+## Version v0.7.4 (Dec 20 2014)
+
+Fix SMTP support for Rails 2.x
+
+## Version v0.7.3 (Dec 19 2014)
+
+Add back accidentally reverted changes
+
+## Version v0.7.2 (Dec 19 2014)
+
+Fix mass adding/removing of unsubscribe methods
+
+## Version v0.7.1 (Dec 1 2014)
+
+SQL performance improvements
+
+## Version v0.7.0 (Mar 23 2014)
+
+Attachments support
+
+## Version v0.6.3 (Mar 22 2014)
+
+Rails 4 compatibility
+
+## Version 0.6.2 (Dec 13, 2012)
+
+Delivery methods with options now work
+
+## Version 0.6.1 (Jan 17, 2012)
+
+Don't use meta_where
+
+## Version 0.6.0 (Nov 29, 2011)
+
+Don't keep the body in finished emails
+
+## Version 0.5.4 (Oct 28, 2011)
+
+Use mail 2.3+
+
+## Version 0.5.3 (Oct 27, 2011)
+
+Fixes a syntax error
+
+## Version 0.5.2 (Oct 27, 2011)
+
+Rails 2.3 compatibility for the bounce processor
+
+## Version 0.5.1 (Oct 27, 2011)
+
+Fix in the process bounces task
+
+## Version 0.5.0 (Oct 27, 2011)
+
+Bounce processing task
+
+## Version 0.4.4 (Oct 15, 2011)
+
+Destroy finished mails when a campaign is deleted.
+
+Addresses a potential issue with marking a finished mail as "opened", when the associated mail campaign has been deleted. Adds MAJOR, MINOR and PATCH version constants.
+
+## Version 0.4.3 (Oct 6, 2011)
+
+Fix potential exception in QueuedMail#interpolate
+
+## Version 0.4.2 (Sep 28, 2011)
+
+We don't require mail 2.3+ anymore, 2.2+ will do.
+
+## Version 0.4.1 (Sep 28, 2011)
+
+Needs mail 2.3+ to avoid ActiveSupport dependency.
+
+## Version 0.4.0 (Sep 27, 2011)
+
+Basic VERP-support.
+
+This version bump is due to improper previous version numbering - when new features were introduced, only the PATCH-level version number was increased.
+
+## Version 0.3.2 (Sep 27, 2011)
+
+Runtime requirements fix.
+
+## Version 0.3.1 (Sep 27, 2011)
+
+Fix gem dependencies.
+
+## Version 0.3.0 (Sep 21, 2011)
+
+Queue locking and basic VERP support.
+
+## Version 0.2.16 (Sep 16, 2011)
+
+Rails 2 compatibility mode fixes.
+
+## Version 0.2.15 (Sep 16, 2011)
+
+Fix syntax error in Tasks::Send.
+
+## Version 0.2.14 (Sep 16, 2011)
+
+More on Rails 2 compatibility in Tasks::Send.
+
+## Version 0.2.13 (Sep 16, 2011)
+
+Rails 2 compatibility in Tasks::Send.
+
+## Version 0.2.12 (Sep 16, 2011)
+
+Length validation fixes in QueuedMail and FinishedMail.
+
+## Version 0.2.11 (Sep 13, 2011)
+
+Settings' defaults.
+
+## Version 0.2.10 (Sep 13, 2011)
+
+Fix generated migration in Rails 2 projects.
+
+## Version 2.8.9 (Sep 13, 2011)
+
+duplicate the migration template file for Rails 2 compatibility.
+
+## Version 0.2.8 (Sep 13, 2011)
+
+Rails 2 migration generator template paths fix.
+
+## Version 0.2.7 (Sep 13, 2011)
+
+Rails 2 migration generator fix + USAGE file. (Remove desc method from the definition of the generator, as Rails 2 does not provide such a method.)
+
+## Version 0.2.6 (Sep 13, 2011)
+
+Fix typo in Rails 2 migration generator and update the readme.
+
+## Version 0.2.5 (Sep 13, 2011)
+
+Fix mistyped Rails 2 generator filename.
+
+## Version 0.2.4 (Sep 13, 2011)
+
+Attempt to fix Rails 2 migration generator.
+
+## Version 0.2.3 (Sep 13, 2011)
+
+Working Rails 3 migration generator.
+
+## Version 0.2.2 (Sep 13, 2011)
+
+Working generator for Rails 2 and 3.
+
+## Version 0.2.1 (Sep 13, 2011)
+
+Migration generator.
+
+## Version 0.2.0 (Sep 2, 2011)
+
+Hit counting in MailCampaign and delivery reports for FinishedMail.
+
+## Version bump to 0.1.0 (Sep 2, 2011)
+
+Initial release.

data/Gemfile

@@ -5,14 +5,13 @@ gemspec
 
 gem "rails", ">= 3.0.0"
 
-group :development do
+group :development, :test do
   gem 'sqlite3'
 
   gem 'guard'
   gem 'guard-bundler'
-  gem 'guard-spork'
-  gem 'guard-rails'
   gem 'guard-rspec'
+  gem 'guard-rails'
 end
 
 group :test do
@@ -21,6 +20,8 @@ group :test do
   gem 'rspec'
   gem 'rspec-rails'
 
+  gem 'factory_girl'
+
   gem 'shoulda-matchers'
   gem 'database_cleaner'
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    smailer (0.7.6)
+    smailer (0.7.8)
       bounce_email (~> 0.2)
       mail (~> 2.3)
 
@@ -44,26 +44,29 @@ GEM
       thread_safe (~> 0.3, >= 0.3.4)
       tzinfo (~> 1.1)
     arel (6.0.0)
-    bounce_email (0.2.2)
+    bounce_email (0.2.6)
       mail
     builder (3.2.2)
     celluloid (0.16.0)
       timers (~> 4.0.0)
-    childprocess (0.5.5)
-      ffi (~> 1.0, >= 1.0.11)
     coderay (1.1.0)
     database_cleaner (1.3.0)
     diff-lcs (1.2.5)
     erubis (2.7.0)
-    ffi (1.9.6)
+    factory_girl (4.5.0)
+      activesupport (>= 3.0.0)
+    ffi (1.9.8)
     formatador (0.2.5)
     globalid (0.3.0)
       activesupport (>= 4.1.0)
-    guard (2.10.2)
+    guard (2.12.6)
       formatador (>= 0.2.4)
       listen (~> 2.7)
       lumberjack (~> 1.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
       pry (>= 0.9.12)
+      shellany (~> 0.0)
       thor (>= 0.18.1)
     guard-bundler (2.0.0)
       bundler (~> 1.0)
@@ -75,10 +78,6 @@ GEM
       guard (~> 2.1)
       guard-compat (~> 1.1)
       rspec (>= 2.99.0, < 4.0)
-    guard-spork (1.5.1)
-      childprocess (>= 0.2.3)
-      guard (>= 1.1)
-      spork (>= 0.8.4)
     hike (1.2.3)
     hitimes (1.2.2)
     i18n (0.7.0)
@@ -97,8 +96,12 @@ GEM
     mini_portile (0.6.2)
     minitest (5.5.1)
     multi_json (1.10.1)
+    nenv (0.2.0)
     nokogiri (1.6.6.2)
       mini_portile (~> 0.6.0)
+    notiffany (0.0.6)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
     pry (0.10.1)
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)
@@ -131,7 +134,7 @@ GEM
       rake (>= 0.8.7)
       thor (>= 0.18.1, < 2.0)
     rake (10.4.2)
-    rb-fsevent (0.9.4)
+    rb-fsevent (0.9.5)
     rb-inotify (0.9.5)
       ffi (>= 0.5.0)
     rspec (3.1.0)
@@ -154,6 +157,7 @@ GEM
       rspec-mocks (~> 3.1.0)
       rspec-support (~> 3.1.0)
     rspec-support (3.1.2)
+    shellany (0.0.1)
     shoulda-matchers (2.7.0)
       activesupport (>= 3.0.0)
     slop (3.6.0)
@@ -182,11 +186,11 @@ PLATFORMS
 DEPENDENCIES
   bundler (>= 1.0.0)
   database_cleaner
+  factory_girl
   guard
   guard-bundler
   guard-rails
   guard-rspec
-  guard-spork
   rails (>= 3.0.0)
   rspec
   rspec-rails

data/README.md

@@ -4,27 +4,33 @@
 
 This project is a simple mailer for newsletters, which implements simple queue processing, basic campaign management, [VERP support](http://en.wikipedia.org/wiki/Variable_envelope_return_path), bounce processing and auto-unsubscribe of invalid emails and also assists you in implementing unsubscribe links in the email messages.
 
-It is intended to be used within a Rails project. It has been tested with Rails 3.0.x, Rails 3.1.0 and Rails 2.3.5.
+It is intended to be used within a Rails project.
+
+### Supported versions of Rails
+
+It has been tested with Rails 3.0.x, Rails 3.1.0 and Rails 2.3.5.
 
 Note: for Rails 3.0.x, you will probably need to use Smailer 0.5.x, because of a version incompatibility with the `mail` Gem.
 
+It should work with Rails 4 as well, but it hasn't been tested extensively there. Testing and PRs for Rails 4 compatibility are welcome. See [this issue](https://github.com/livebg/smailer/issues/16) for more info.
+
 ## Install
 
 ### Install the gem
 
 For Rails 3 projects, add the following to your `Gemfile`:
 
-	gem 'smailer'
+    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. 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
+    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:
 
-	rails g smailer:migration && bundle exec rake db:migrate
+    rails g smailer:migration && bundle exec rake db:migrate
 
 For Rails 2.x projects, use `script/generate smailer_migration && rake db:migrate` to generate and run the migration.
 
@@ -32,13 +38,17 @@ For Rails 2.x projects, use `script/generate smailer_migration && rake db:migrat
 
 Since the plugin has been designed to be managed via an admin UI, its settings are stored in a simple key-value table, interfaced by the `Smailer::Models::Property` model. Here is some sample data you can use to initialize your settings with:
 
-	Smailer::Models::Property.create! :name => 'queue.max_retries', :value => '0', :notes => '0 = unlimited.'
-	Smailer::Models::Property.create! :name => 'queue.max_lifetime', :value => '172800', :notes => 'In seconds; 0 = unlimited.'
-	Smailer::Models::Property.create! :name => 'queue.batch_size', :value => '100', :notes => 'Emails to send per run.'
-	Smailer::Models::Property.create! :name => 'finished_mails.preserve_body', :value => 'false', :notes => 'If this one is set to true, it will take more space in the DB. Use with caution and for debugging purposes only.'
+    Smailer::Models::Property.create! :name => 'queue.max_retries', :value => '0', :notes => '0 = unlimited.'
+    Smailer::Models::Property.create! :name => 'queue.max_lifetime', :value => '172800', :notes => 'In seconds; 0 = unlimited.'
+    Smailer::Models::Property.create! :name => 'queue.batch_size', :value => '100', :notes => 'Emails to send per run.'
+    Smailer::Models::Property.create! :name => 'finished_mails.preserve_body', :value => 'false', :notes => 'If this one is set to true, it will take more space in the DB. Use with caution and for debugging purposes only.'
 
 These properties and values are also the defaults.
 
+## Upgrading
+
+If you have an older version of the gem and would like to upgrade to a newer one, take a look [at the changelog](CHANGELOG.md).
+
 ## Usage and documentation
 
 Sending out newsletters consists of a couple of steps:
@@ -52,37 +62,56 @@ Sending out newsletters consists of a couple of steps:
 
 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
-
-	# create a corresponding mail campaign
-	campaign_params = {
-		:from      => 'noreply@example.org',
-		:subject   => 'My First Campaign!',
-		:body_html => '<h1>Hello</h1><p>World</p>',
-		:body_text => 'Hello, world!',
-		:mailing_list_id => list.id,
-	}
-	campaign = Smailer::Models::MailCampaign.new campaign_params
-	campaign.add_unsubscribe_method :all
-	campaign.save!
-
-	# Add attachments
-	campaign.add_attachment 'attachment.pdf', 'url_or_file_path_to_attachment'
-
-	# enqueue mails to be sent out
-	subscribers = %w[
-		subscriber@domain.com
-		office@company.com
-		contact@store.com
-	]
-	subscribers.each do |subscriber|
-	  campaign.queued_mails.create! :to => subscriber
-	end
+    # locate the mailing list we'll be sending to
+    list = Smailer::Models::MailingList.first
+
+    # create a corresponding mail campaign
+    campaign_params = {
+      :from      => 'noreply@example.org',
+      :subject   => 'My First Campaign!',
+      :body_html => '<h1>Hello</h1><p>World</p>',
+      :body_text => 'Hello, world!',
+      :mailing_list_id => list.id,
+    }
+    campaign = Smailer::Models::MailCampaign.new campaign_params
+    campaign.add_unsubscribe_method :all
+
+    # Add attachments
+    campaign.add_attachment 'attachment.pdf', 'url_or_file_path_to_attachment'
+
+    campaign.save!
+
+    # enqueue mails to be sent out
+    subscribers = %w[
+      subscriber@domain.com
+      office@company.com
+      contact@store.com
+    ]
+    subscribers.each do |subscriber|
+      campaign.queued_mails.create! :to => subscriber
+    end
+
+### One-off emails
+
+You can send one-off emails that each have a different mail template:
+
+    campaign = Smailer::Models::MailCampaign.first
+
+    # The mail template is first copied from the mail campaign and then any
+    # changes you make are stored in the newly created copy.
+    # In this example, the subject and from fields are copied from the campaign.
+    campaign.queued_mails.create! :to => 'subscriber@domain.com', :body_html => 'my custom body', :body_text => 'my custom body'
+
+    # Changing the campaign now won't change anything in the one-off queued mails.
+
+    # Sending two mails to the same person for a single campaign:
+    campaign.queued_mails.create! :to => 'subscriber@domain.com', :body_html => 'second custom body', :body_text => 'second custom body', require_uniqueness => false
+
+You can change the `from`, `subject`, `body_html`, `body_text` and you can also call `add_attachment`. For more info check [Smailer::Models::QueuedMail](lib/smailer/models/queued_mail.rb).
 
 ### Attachments
 
-You can have zero or more attachments to any mail campaign. As demonstrated in the example above, you add them to the campain using the `MailCampaign#add_attachment(file_name, url_or_path)` method.
+You can have zero or more attachments to any mail campaign. As demonstrated in the example above, you add them to the campaign using the `MailCampaign#add_attachment(file_name, url_or_path)` method.
 
 Any attached files will be referenced at the moment of sending and must be reachable and readable by the send task. Currently, `open-uri` is used to fetch the content of the path or URI. The maximum length of the path/URI field is 2048 symbols.
 
@@ -101,31 +130,31 @@ 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 following email address: %{escaped_email}</p>
+    <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 following email address: %{escaped_email}</p>
 
 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
+    @email = Smailer::Models::MailKey.find_by_key(params[:email_key]).try(:email)
+    raise ActiveRecord::RecordNotFound unless @email
 
-	# here you have the @email address of the user who wishes to unsubscribe
-	# and can mark it in your system accordingly (or remove it from your lists altogether)
+    # here you have the @email address of the user who wishes to unsubscribe
+    # and can mark it in your system accordingly (or remove it from your lists altogether)
 
 ### Sending mails
 
 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 :return_path_domain => 'bounces.mydomain.com', :verp => true
-	    result.each do |queue_item, status|
-	      puts "Sending #{queue_item.to}: #{status}"
-	    end
-	  end
-	end
+    # 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 :return_path_domain => 'bounces.mydomain.com', :verp => true
+        result.each do |queue_item, status|
+          puts "Sending #{queue_item.to}: #{status}"
+        end
+      end
+    end
 
 This task can be executed via `RAILS_ENV=production bundle exec rake smailer:send_batch` (provided you are running it on your production servers).
 
@@ -141,26 +170,26 @@ This can be done via a simple cron task, which runs daily (or whatever) on your
 
 Suppose you manage your site's newsletter subscriptions via a `Subscription` model, which has two boolean flags -- `subscribed` and `confirmed` and also an `email` field. You could implement a simple Rake task to be run via a cron daemon this way:
 
-	task :process_bounces => :environment do
-	  subscribed_checker = lambda do |recipient|
-	    Subscription.confirmed.subscribed.where(:email => recipient).first.present?
-	  end
-
-	  Smailer::Tasks::ProcessBounces.execute({
-	    :server             => 'bounces.mydomain.com',
-	    :username           => 'no-reply@bounces.mydomain.com',
-	    :password           => 'mailbox-password',
-	    :subscribed_checker => subscribed_checker,
-	  }) do |unsubscribe_details|
-	    subscription = Subscription.confirmed.subscribed.where(:email => unsubscribe_details[:recipient]).first
-
-	    if subscription
-	      subscription.subscribed = false
-	      subscription.unsubscribe_reason = 'Automatic, due to bounces'
-	      subscription.save!
-	    end
-	  end
-	end
+    task :process_bounces => :environment do
+      subscribed_checker = lambda do |recipient|
+        Subscription.confirmed.subscribed.where(:email => recipient).first.present?
+      end
+
+      Smailer::Tasks::ProcessBounces.execute({
+        :server             => 'bounces.mydomain.com',
+        :username           => 'no-reply@bounces.mydomain.com',
+        :password           => 'mailbox-password',
+        :subscribed_checker => subscribed_checker,
+      }) do |unsubscribe_details|
+        subscription = Subscription.confirmed.subscribed.where(:email => unsubscribe_details[:recipient]).first
+
+        if subscription
+          subscription.subscribed = false
+          subscription.unsubscribe_reason = 'Automatic, due to bounces'
+          subscription.save!
+        end
+      end
+    end
 
 For more info and also if you'd like to adjust the unsubscribe rules, take a look at the `ProcessBounces.execute` method and its options. It's located in `lib/smailer/tasks/process_bounces.rb`. A few extra options are available, such as `:logger` callbacks (which defaults to `puts`), default action for unprocessed bounces, etc.
 
@@ -168,10 +197,15 @@ For more info and also if you'd like to adjust the unsubscribe rules, take a loo
 
 * Tests, tests, tests
 
+## Tests
+
+    ./setup-test-db
+    bundle exec rspec
+
 ## Contribution
 
 Patches are always welcome. In case you find any issues with this code, please use the project's [Issues](http://github.com/mitio/smailer/issues) page on Github to report them. Feel free to contribute! :)
 
 ## License
 
-Released under the MIT license.
+Released under the MIT license.