= sanitize_email

This gem allows you to globally override your mail delivery settings.  It's particularly helpful when you want to omit the delivery of email (e.g. in development/test environments) or alter the to/cc/bcc (e.g. in staging or demo environments) of all email generated from your application.

It is a "configure it and forget it" type gem that requires very little setup.  It includes some very innocuous monkey patching of ActionMailer::Base to work its magic.

Peter Boling wrote the plugin that this gem is derived from.  It currently solves three common problems in ruby web applications that use ActionMailer:

=== Working Locally with Production Data

Peter described this common problem in his original plugin implementation as such:

# I have a production site with live data.
# I dump the live data and securely transfer it to another machine (rync -e ssh), and import it using scripts that I will soon open source to.
# On this separate machine (staging, or development) I run tests, and test various features.
# I usually want the emails to get sent from these non-production environments so I can verify what they look like when sent, but I don't ever want to risk them getting sent to addresses that are not mine.

=== Re-routing Email on a Staging or QA Server

Another very important use case for me is to transparently re-route email generated from a staging or QA server to an appropriate person.  For example, it's common for us to set up a staging server for a client to use to view our progress and test out new features.  It's important for any email that is generated from our web application be delivered to the client's inbox so that they can review the content and ensure that it's acceptable.  Similarly, we set up QA instances for our own QA team and we use rails-caddy to allow each QA person to configure it specifically for them.

=== Testing Email from a Hot Production Server

If you install this gem on a production server (which I don't always do), you can load up script/console and override the to/cc/bcc on all emails for the duration of your console session.  This allows you to poke and prod a live production instance, and route all email to your own inbox for inspection.  The best part is that this can all be accomplished without changing a single line of your application code.

== Install

  gem sources -a http://gems.github.com/
  gem install jtrupiano-sanitize_email

== Setup

It only requires a few lines of configuration:

* Rails 1.x: Add to bottom of environment.rb
		
* Rails 2.x: Use an initializer, stick it in any initializer file, or create a new one for sanitize_email
		
Add this bit and customize for your app:

<pre>
  # Settings for sanitize_email gem.  These can be overridden in individual config/%env%/environment.rb files.

  require 'sanitize_email'
  ActionMailer::Base.sanitized_recipients = "jtrupiano@gmail.com"
  ActionMailer::Base.sanitized_bcc = nil
  ActionMailer::Base.sanitized_cc = nil
  
  # optionally, you can configure sanitize_email to to include the "real" email address as the 'user name' of the
  # "sanitized" email (e.g. "real@address.com <sanitized@email.com>")
  ActionMailer::Base.use_actual_email_as_sanitized_user_name = true # defaults to false

  # These are the environments whose outgoing email BCC, CC and recipients fields will be overridden!  
  # All environments not listed will be treated as normal.
  ActionMailer::Base.local_environments = %w( development test staging )
</pre>

Keep in mind, this is ruby (and possibly rails), so you can add conditionals or utilize different environment.rb files to customize these settings on a per-environment basis.

But wait there's more:

Let's say you have a method in your model that you can call to test the signup email.
You want to be able to test sending it to any user at any time... but you don't want
the user to ACTUALLY get the email, even in production. A dilemma, yes?  Not anymore!

All your mailers get a force_sanitize class method which takes precedence over the environment override.

When force_sanitize is nil it will not be used by sanitize_email to determine if it should override the recipients, bcc, and cc.


== Example

So here's how you can use force_sanitize to override the override.

Even if you set:

  ActionMailer::Base.local_environments = %w( development )

and are in the development environment, you can override the override anywhere in your code.

<pre>
  class User < ActiveRecord::Base
    def test_signup_email_me_only
      UserMailer.force_sanitize = true
      UserMailer.deliver_signup_notification(self)
      UserMailer.force_sanitize = nil
    end

    def test_signup_email_user_only
      UserMailer.force_sanitize = false
      UserMailer.deliver_signup_notification(self)
      UserMailer.force_sanitize = nil
    end

    # this third method would conditionally use the overridden recipients based on current Rails environment
    def test_signup_email_environment
      UserMailer.deliver_signup_notification(self)
    end

  end
</pre>

Load the console with ruby script/console and regardless of what environment you are in:

	> User.find(4).test_signup_email_me_only
	
and the email will have it's recipients, bcc, and cc overridden to be whatever you set the sanitized values to be.
Then if you want to send it to the actual user, instead of yourself

	> User.find(4).test_signup_email_user_only

That's it!  Enjoy!

Copyright (c) 2009 John Trupiano of SmartLogic Solutions, LLC
Copyright (c) 2008 Peter H. Boling of 9thBit LLC
Released under the MIT license