= sanitize_email {<img src="https://codeclimate.com/badge.png" />}[https://codeclimate.com/github/pboling/sanitize_email] {<img src="https://secure.travis-ci.org/pboling/sanitize_email.png?branch=master" alt="Build Status" />}[http://travis-ci.org/pboling/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 uses the 'register_interceptor' API of ActionMailer or the Mail gem.  It should work with Rails >3 or any Ruby app that is using Mail or ActionMailer gems.

It currently solves five (3!) common problems in ruby web applications that use email:

=== #1 Working Locally with Production Data

* 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 a few rake tasks here: http://github.com/pboling/sir-du-bob
* On this separate machine (staging, or development) I run tests, and test various features which often send out email (registration/signup, order placement, etc.)
* 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.

=== #2 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}[http://github.com/jtrupiano/rails-caddy] to allow each QA person to configure it specifically for them.

=== #3 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 Like a Boss

  [sudo] gem install sanitize_email

== Setup With An Axe

Customize and add to an initializer:

  SanitizeEmail::Config.configure do |config|
    config[:sanitized_recipients] = 'to@sanitize_email.org'
    config[:sanitized_cc] =         'cc@sanitize_email.org'
    config[:sanitized_bcc] =        'bcc@sanitize_email.org'
    # sanitize emails from development and test, or set whatever logic should turn sanitize_email on and off here:
    config[:activation_proc] =   Proc.new { %w(development test).include?(Rails.env) }
    config[:use_actual_email_prepended_to_subject] = true   # or false
    config[:use_actual_email_as_sanitized_user_name] = true # or false
  end

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!

To override the environment based switch use force_sanitize, which is normally nil, and ignored by default. When set to true or false it will turn sanitization on or off:

  SanitizeEmail.force_sanitize = true

== Deprecations

Sometimes things get deprecated (meaning they still work, but are noisy about it).  If this happens to you, and you like your head in the sand, call this number:

  SanitizeEmail::Deprecation.deprecate_in_silence = true


== Authors

Peter Boling is the original author of the code, and current maintainer of both the rails 2 and rails 3 development tracks.
John Trupiano did the initial gemification and some refactoring.

== Contributors

George Anderson's work / improvements have been pulled in, along with several other contributors, which can be seen in the Network view on github. Thanks!

== References
* {Source Code}[http://github.com/pboling/sanitize_email]
* {Gem Release Announcement}[http://blog.smartlogicsolutions.com/2009/04/25/reintroducing-sanitize_email-work-with-production-email-without-fear/]
* {Peter's Original Writeup}[http://galtzo.blogspot.com/2008/11/sanitize-email-never-worry-about.html]
* {Using sanitize_email to Preview HTML Emails Locally}[http://blog.smartlogicsolutions.com/2009/04/30/using-sanitize-email-to-preview-html-emails-locally/]

Copyright (c) 2008-2012 {Peter H. Boling}[http://www.peterboling.com/about.html] of {9thBit LLC}[http://www.peterboling.com/]
Copyright (c) 2009 {John Trupiano}[http://smartlogicsolutions.com/wiki/John_Trupiano] of {SmartLogic Solutions, LLC}[http://www.smartlogicsolutions.com]
Released under the MIT license