kbaum-mail 2.1.2.1

data/CHANGELOG.rdoc

@@ -0,0 +1,289 @@
+== Thu Jan 28 00:25:02 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Added TMM1's patch to not raise errors if a email is not multipart/report
+* Added html_part and text_part now return the first text/html or text/plain part they find. Order is from top to bottom of the email, all parts, flattened.
+* Version bump to 2.1.2
+
+== Mon Jan 25 11:36:13 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Added ability for address fields to init on an array instead of just a string.
+* Version bump to 2.1.1
+
+== Mon Jan 25 10:36:33 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Now passes a block to the delivery handler, which can just call yield if it want's Mail to just do it's normal delivery method
+* Moved Mail.deliveries into Mail::TestMailer.deliveries. Now only gets mail appended to it if you are sending with the :test delivery_method (only for testing)
+* Version bump to 2.1.0
+
+== Mon Jan 25 01:44:13 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Change :deliver! to deliver a mail object, bypassing the :perform_deliveries and :raise_delivery_errors flags, also does not append the mail object to Mail.deliveries, thus the ! (dangerous).  The intended use for :deliver! is for people wanting to have their own delivery_handler (like ActionMailer uses) to track and handle delivery failures.
+* Added :delivery_handler to Message.  Allows you to pass an object that will be sent :deliver_mail(self) by the Mail::Message instance when it is sent :deliver and bypasses the usual delivery method.
+* Changed :perform_deliveries flag to be more consistent with it's name, mail will not append itself to the Mail.deliveries collection if :perform_deliveries is false
+
+== Sat Jan 23 23:49:50 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Version bump to 2.0.5
+* Added :raise_delivery_errors to Mail::Message, if set to false will silently rescue all errors raised by the delivery methods, set to true by default
+
+== Sat Jan 23 23:28:42 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Version bump to 2.0.4
+* Added :perform_deliveries to mail, will not actually call deliver on the delivery method if this is set to false, set to true by default.
+* Added @delivery_notification_observers to mail messages, you can register an observer with mail by calling mail.register_for_delivery_notification(observer) and then when mail is told to :deliver it will call your observer with observer.delivered_email(self).  It will call your observer if it actually performed the delivery or not (that is, irregardless of the :perform_deliveries flag)
+* Added ability to overwrite the Mail.deliveries store with an object of your choice instead of just an array, this is a good way to find out if something actually got delivered as if :perform_deliveries is false, this collection will not get the mail message appended
+
+== Sat Jan 23 05:32:53 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Version bump to 2.0.3
+* Made body.sort_parts! recursive, to do the entire body
+* Added ability to use << on the results returned by the various address fields, ie, mail.to << 'new@address' now works
+* Message now adds multipart/mixed as the content type if nothing is set and there are parts to the message
+* Added #display_names and #addrs to all address fields.  #addrs returns the actual Mail::Address object for each address in the field.
+* Body should call to_s on given input... incase someone gave it an IO.readlines result (Array)
+* 
+
+== Thu Jan 21 05:27:17 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Version bump to 2.0.2
+* Major change to attachments, add_file now only accepts
+  {:filename => 'full/path/to/file.png'} or 
+  {:filename => 'file.png', :content => 'string of file content'}
+  you can also now do mail.attachments['filename.png'] = File.read('path/to/file.png')
+  which is nice too!
+
+== Fri Jan 15 09:20:51 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Rewrote all network classes to not use singletons.  Means different Mail::Message objects can have different delivery methods.
+* Added examples for how to send via GMail, MobileMe, Sendmail, File etc.
+* Version bump to 2.0.0 as Network API changed drastically, now not a singleton class.
+* Fixed that return-path should only return one address
+
+== Thu Jan 14 10:41:22 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Version update to 1.6.0 - API change on mail.address_fields to always return arrays
+* Updated all message.address_field methods to always return arrays, so mail.from #=> ['one@address.com'] now, is least surprise
+* Updated handling of empty group lists so it didn't crash
+
+== Thu Jan 12 10:41:47 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Version 1.5.3, handling invalid input on fields.  Highly recommended update
+* Updated fields to always try parsing the given data (unless blank). This allows mail to catch invalid input and return UnstructuredFields. Makes mail a lot more resistant to invalid input.
+
+== Fri  8 Jan 2010 00:00:08 UTC Mikel Lindsaar <raasdnil@gmail.com>
+
+* Version bump to 1.5.2
+
+== Fri  8 Jan 8:55:49 2010 +1100 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Updated Sendmail and SMTP delivery methods to use return-path if present
+* Fix up a lot of content-type parsing problems
+* Updating compat listing
+* Moving error emails into one directory
+* Moving error emails into one directory
+* Initializing @tls variable to remove warnings
+* Moved default corpus directory
+* Fixed up git ignore file
+
+== Thu  6 Jan 2010 23:59:29 UTC Mikel Lindsaar <raasdnil@gmail.com>
+
+* Added compatibility list to Readme.rdoc
+* Fixing encoding of return path to be per RFC 2822, adding angle brackets around the addr_spec
+* Specs covering return path setting and preserving
+
+== Thu  5 Jan 2010 23:59:48 UTC Mikel Lindsaar <raasdnil@gmail.com>
+
+* Moving the require for tlsmail for Ruby 1.8.6 into mail.rb
+
+== Sun Jan  3 00:08:06 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Version bump to 1.5.0
+
+* Major API change in Message#field_name.  This WILL break your applications that use Mail.  Message#field_name now returns good, intelligent, default values.  You can still access the field object by calling Message#[:field_name] or Message#['field_name'].
+
+== Sat Jan  2 04:12:53 UTC 2010 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Message-ID, Content-ID, References et al, now return the default value of the message ID without the angle brackets, as per RFC 2822, "Semantically, the angle bracket characters are not part of the msg-id; the msg-id is what is contained between the two angle bracket characters."
+
+* Message class now has getter and setter methods for all the supported field types explicitly.  This allows us to return a "default" value for all fields.
+
+* All address fields, when called from Message#to or Message#from or the like, return either a string of the address spec (mikel@test.lindsaar.net) if it is a single entry, or an array of address specs if there is more than one ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']
+
+== Mon 28 Dec 2009 01:21:52 UTC Mikel Lindsaar <raasdnil@gmail.com>
+
+* Added sorting of parts, default is text/plain, then text/enriched and text/html.  Access through  Body#set_sort_order and Body#sort_parts! (called from Body#encode automatically)
+* Version bump to 1.4.2
+
+== Sun Dec 27 10:38:24 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Updating treetop and mail to initialize uninitialized instance variables to
+  nil
+* Version bump to 1.4.1
+
+== Sun Dec 27 09:51:27 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Version bump to 1.4 because now :to_s calls :decoded for all fields and body 
+  while :to_s calls :encoded for Message and Header containers.  Makes sense... 
+  really.
+
+== Sun Dec 27 07:30:02 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Changed fields to default to :decoded on :to_s, all container objects
+  retain :encoded as the default for :to_s
+
+== Thu Dec 17 06:35:05 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Fixed parsing error 'Subject: =?ISO-8859-1?Q?Re=3A_ol=E1?=' (has a new line embedded)
+
+== Thu Dec 17 02:14:23 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Version 1.3.4
+* Vendor'd treetop
+
+== Thu Dec 17 01:32:00 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Version 1.3.3
+* Removed dependency on treetop, don't need it at runtime
+
+== Wed Dec 16 23:48:46 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Version 1.3.2
+* Resolved Ruby 1.9.1-head not working because File.basename only accepts US-ASCII or 8Bit
+
+== Sun Dec 13 01:06:17 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Version 1.3.1
+* Resolved Issue #18 - Wrong instance variable name
+* Resolved Issue #15 - Duplicate block call
+
+== Thu Dec 10 21:25:37 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Resolved Issue #13 - replacing From field results in from field becoming optional field.
+
+== Thu  3 Dec 2009 00:52:12 UTC Mikel Lindsaar <raasdnil@gmail.com>
+
+* Added POP upgrades from Nicolas Fouché
+* Added patch to handle multiple from lines in email from Luke Grimstrup
+
+== Mon Nov 23 23:34:22 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Resolved Issue #12 - Wrong comment in smtp.rb
+
+== Mon Nov 23 22:35:50 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Changed the way attachments are added so that it does not break depending on the order of the Hash passed in.
+* Version bump to 1.3.0 - Now works with Edge ActionMailer, MRI 1.8.6, 1.8.7, 1.9.1, all tests passing
+
+== Sun Nov 22 12:19:44 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Added check on add_part to make sure if there is already a body, and if so, make a text_part of the body
+* Fixing up attachment adding and making sure multipart emails always have boundaries
+* Change Message#attachments to now recursively return all attachments in the email in an ordered flattened array
+* Added ability for Mail::Message to accept {:headers => {'custom-header' => 'value', 'another-custom-header' => 'value'}} as a param on init
+* Adding ability to Mail::Message to add a part via :part(params) with optional block
+* Fixed up QP encoding forcing underscores into everything with a space
+* Added ReturnPathField#address
+* Updating gem loads and active support loads
+
+== Sat Nov 21 12:52:46 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Changed Mail::Encodings to clean it up, added in unquote_and_convert_to as well as refactor in this area
+
+== Thu Nov 19 04:16:10 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Added sendmail support from (Simon Rozet)
+* Changed to bundler for gem dependancies and moved gem generation into rakefile (Simon Rozet)
+* Bumped to 1.2.6 for sendmail support
+
+== Wed Nov 18 04:26:21 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Changed Encodings.param_encode(string) so it intelligently encodes and quotes needed
+  items and leaves plain, no special char, US-ASCII alone unquoted.
+
+== Sat Nov 14 08:20:21 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Resolved Issue #10 - empty/nil cc/bcc field causes exception (Mail::Field::ParseError)
+
+== Fri Nov 13 00:31:04 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Hacked and mutilated the network section, made it easier to extend out with other
+  delivery and retriever methods.  API changed SLIGHTLY with this.  Please check the
+  readme
+* Resolved Issue #8 - Mail::SMTP now delivers to all mail.destinations
+* Version bump to 1.2.5
+
+== Thu Nov 12 02:58:01 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Resolved Issue #5 - Message ID not handling multiple periods in left hand side
+* Resolved Issue #6 - Ordering of add_file and body items causes invalid emails
+
+== Tue Nov 10 08:15:14 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Resolved Issue #5 - Message ID generation issue
+* Resolved Issue #7 - README add_file examples don't seem to work - Updated readme and
+  rdoc in Message#add_file
+
+== Mon Nov  9 23:38:33 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Added ability to create new email via a hash or hash-like object. <mikel>
+* Moved all of the Part init into the Message class.  Part now just uses Message's init,
+  also moved all the attachment related functions into Message.  As Part is a subclass
+  of message, you shouldn't see any interface changes here.
+
+== Fri Nov  6 22:52:10 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* a6ef2b4: Fixed Issue #4 - Can't call encoding on non existant 
+  content-transer-encoding header
+
+== Fri Nov  6 00:51:55 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Handled unstructured field folding "blank" lines
+* Fixed error in header.rb that created fields into an array, instead of a FieldList, resulting
+  in mail.encode returning a random sort order on the header.
+* Made unstructured fields attempt to decode their values on :decode
+
+== Thu Nov  5 04:45:31 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* 2acb70a: Closes Issue #1 - Handling badly formatted content-type fields <mikel>
+
+== Wed Nov  4 23:24:32 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* 2b5d608: Closes Issue #2 - Empty header field values not parsing <mikel>
+* Version bumb to 1.2.1
+
+== Wed Nov  4 12:54:43 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Renamed Mail::Message.encode! to Mail::Message.ready_to_send!, deprecated :encode! <mikel>
+* Rewrote encoding and decoding methods on all classes.  Adds a lot of boiler plate code, but allows us to
+  be really precise in each field type that needs custom encoding.  Now all encoding is done by the field_type
+  itself.  Need to follow through on the body. <mikel>
+* Bump version to 1.2.0 due to changes of :encoded, :decoded behaviour <mikel>
+
+== Tue Nov  3 00:59:45 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Tested mail against entire Enron set (2.3gb) and the Trec 2005 set (0.5gb), ~ half a million emails without crashing <jlindley>
+* Some headers only can appear once, enforce during header parse assignment. <jlindley>
+* Convert empty bodies into empty arrays instead of nil. <jlindley>
+* Handle blank content dispositions. <jlindley>
+* Mention Trec 2005 Spam Corpus in readme <jlindley>
+* Add 'rake corpus:verify_all' to allow parse checks in bulk. <jlindley>
+* Added handling of multi value parameters, like filename*1*="us-ascii'en'blah" filename*2="bleh" <mikel>
+* Added dependency on ActiveSupport 2.3 or higher <mikel>
+
+== Sun Nov  1 12:00:00 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* handle OpenSSL::SSL::VERIFY_NONE returning 0 <jlindley>
+* doing Mail.new { content_type [text, plain, { charset => UTF-8 }] } is now 
+  possible (content type accepts an array) <mikel>
+
+== Sat Oct 31 11:00:41 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Fixed attachment handling, so mail can find attachment from a content-type,
+content-disposition or content-location
+* Added content-location field and parser
+* Added message.has_attachments? for ActionMailer friendliness
+* Added attachment.original_filename for ActionMailer friendliness
+
+== Sat Oct 25 13:38:01 UTC 2009 Mikel Lindsaar <raasdnil@gmail.com>
+
+* Birthday, Mail released as a gem... phew

data/README.rdoc

@@ -0,0 +1,575 @@
+= Mail
+
+== Introduction
+
+Mail is an internet library for Ruby that is designed to handle emails
+generation, parsing and sending in a simple, rubyesque manner.
+
+The purpose of this library is to provide a single point of access to handle
+all email functions, including sending and receiving emails.  All network
+type actions are done through proxy methods to Net::SMTP, Net::POP3 etc.
+
+Built from my experience with TMail, it is designed to be a pure ruby
+implementation that makes generating, sending and parsing emails a no
+brainer.
+
+It is also designed form the ground up to work with Ruby 1.9.  This is because
+Ruby 1.9 handles text encodings much more magically than Ruby 1.8.x and so
+these features have been taken full advantage of in this library allowing
+Mail to handle a lot more messages more cleanly than TMail.  Mail does run on
+Ruby 1.8.x... it's just not as fun to code.
+
+Finally, Mail has been designed with a very simple object oriented system
+that really opens up the email messages you are parsing, if you know what
+you are doing, you can fiddle with every last bit of your email directly.
+
+== Compatibility
+
+Mail is tested and works on the following platforms:
+
+* ree-1.8.7-2009.10 [ x86_64 ]
+* ruby-1.8.6-p383 [ x86_64 ]
+* ruby-1.8.7-p248 [ x86_64 ]
+* ruby-1.9.1-head [ x86_64 ]
+* ruby-1.9.1-p376 [ x86_64 ]
+
+Mail seems to work fine on JRuby as well, however, the Base64 and Quoted-Printable
+encoding methods are implemented differently and return different values so 6 
+specs fail.  This needs to be triple checked if all OK.
+
+* jruby-1.4.0 [x86_64-java]
+
+== Discussion
+
+If you want to discuss mail with like minded individuals, please subscribe to
+the Google Group http://groups.google.com/group/mail-ruby
+
+== Current Capabilities of Mail
+
+* RFC2822 Support, Reading and Writing
+* RFC2045-2049 Support for multipart emails
+* Support for creating multipart alternate emails
+* Support for reading multipart/report emails & getting details from such
+* Support for multibyte emails - needs quite a lot of work and testing
+* Wrappers for File, Net/POP3, Net/SMTP
+
+Mail is RFC2822 compliant now, that is, it can parse and generate valid US-ASCII
+emails.  There are a few obsoleted syntax emails that it will have problems with, but
+it also is quite robust, meaning, if it finds something it doesn't understand it will
+not crash, instead, it will skip the problem and keep parsing.  In the case of a header
+it doesn't understand, it will initialise the header as an optional unstructured
+field and continue parsing.
+
+This means Mail won't (ever) crunch your data (I think).
+
+You can also create MIME emails.  There are helper methods for making a 
+multipart/alternate email for text/plain and text/html (the most common pair)
+and you can manually create any other type of MIME email.
+
+== Roadmap
+
+Next TODO:
+
+* Improve MIME support for character sets in headers, currently works, mostly, needs
+  refinement.
+* Add IMAP wrapper
+
+== Testing Policy
+
+Basically... we do BDD on Mail.  No method gets written in Mail without a
+corresponding or covering spec.  We expect as a minimum 100% coverage
+measured by RCov.  While this is not perfect by any measure, it is pretty
+good.  Additionally, all functional tests from TMail are to be passing before
+the gem gets released.
+
+It also means you can be sure Mail will behave correctly.
+
+== API Policy
+
+No API removals within a single point release.  All removals to be depreciated with
+warnings for at least one MINOR point release before removal.
+
+Also, all private or protected methods to be declared as such - though this is still I/P.
+
+== Installation
+
+Installation is fairly simple, I host mail on gemcutter, so you can just do:
+
+ # gem install mail
+
+if you are on gemcutter, if you aren't, you can by doing:
+
+ # gem install gemcutter
+ # gem tumble
+ # gem install mail
+ 
+Warning though, the above will change your first gem repository to gemcutter, this
+may or may not be a problem for you.
+
+If you want to install mail manually, you can download the gem from github and do:
+
+ # gem install mail-1.2.1.gem
+ 
+== Encodings
+
+If you didn't know, handling encodings in Emails is not as straight forward as you
+would hope.
+
+I have tried to simplify it some:
+
+1. All objects that can render into an email, have an :encoded method.  Encoded will
+   return the object as a complete string ready to send in the mail system, that is,
+   it will include the header field and value and CRLF at the end and wrapped as
+   needed.
+   
+2. All objects that can render into an email, have a :decoded method.  Decoded will
+   return the object's "value" only as a string.  This means it will not include
+   the header fields (like 'To:' or 'Subject:').
+   
+3. By default, calling :to_s on a container object will call it's encoded method, while
+   :to_s on a field object will call it's decoded method.  So calling :to_s on a Mail
+   object will return the mail, all encoded ready to send, while calling :to_s on the
+   From field or the body will return the decoded value of the object.  The header object
+   of Mail is considered a container.  If you are in doubt, call :encoded, or :decoded
+   explicitly, this is safer if you are not sure.
+   
+4. Structured fields that have parameter values that can be encoded (e.g. Content-Type) will
+   provide decoded parameter values when you call the parameter names as methods against
+   the object.
+   
+5. Structured fields that have parameter values that can be encoded (e.g. Content-Type) will
+   provide encoded parameter values when you call the parameter names through the 
+   object.parameters['<parameter_name>'] method call.
+ 
+== Contributing
+
+Please do!  Contributing is easy in Mail:
+
+1. Check the Reference RFCs, they are in the References directory, so no excuses.
+2. Open a ticket on github, maybe someone else has the problem too
+3. Make a fork of my github repository
+4. Make a spec driven change to the code base
+5. Make sure it works and all specs pass, on Ruby versions 1.8.6, 1.8.7 and 1.9
+6. Update the README if needed to reflect your change / addition
+7. With all specs passing push your changes back to your fork
+8. Send me a pull request
+
+== Usage
+
+All major mail functions should be able to happen from the Mail::module.
+So, you should be able to just "require 'mail'" to get started.
+
+=== Making an email
+
+ require 'mail'
+ 
+ mail = Mail.new do
+      from 'mikel@test.lindsaar.net'
+        to 'you@test.lindsaar.net'
+   subject 'This is a test email'
+      body File.read('body.txt')
+ end
+
+ mail.to_s #=> "From: mikel@test.lindsaar.net\r\nTo: you@...
+
+=== Making an email, have it your way:
+
+ require 'mail'
+ 
+ mail = Mail.new do
+   body File.read('body.txt')
+ end
+
+ mail['from'] = 'mikel@test.lindsaar.net'
+ mail[:to]    = 'you@test.lindsaar.net'
+ mail.subject = 'This is a test email'
+ 
+ mail.to_s #=> "From: mikel@test.lindsaar.net\r\nTo: you@...
+
+=== Don't Worry About Message IDs:
+
+ require 'mail'
+ 
+ mail = Mail.new do
+     to 'you@test.lindsaar.net'
+   body 'Some simple body'
+ end
+
+ mail.to_s =~ /Message\-ID: <[\d\w_]+@.+.mail/ #=> 27
+ 
+Mail will automatically add a Message-ID field if it is missing and
+give it a unique, random Message-ID along the lines of:
+
+ <4a7ff76d7016_13a81ab802e1@local.fqdn.mail>
+ 
+=== Or do worry about Message-IDs:
+
+ require 'mail'
+ 
+ mail = Mail.new do
+          to 'you@test.lindsaar.net'
+  message_id '<ThisIsMyMessageId@some.domain.com>'
+        body 'Some simple body'
+ end
+ 
+ mail.to_s =~ /Message\-ID: <ThisIsMyMessageId@some.domain.com>/ #=> 27
+
+Mail will take the message_id you assign to it trusting that you know
+what you are doing.
+
+=== Sending an email:
+
+Mail defaults to sending via SMTP to local host port 25.  If you have a 
+sendmail or postfix daemon running on on this port, sending email is as
+easy as:
+
+ Mail.deliver do
+       from 'me@test.lindsaar.net'
+         to 'you@test.lindsaar.net'
+    subject 'Here is the image you wanted'
+       body File.read('body.txt')
+   add_file '/full/path/to/somefile.png'
+ end
+
+or
+ 
+ mail = Mail.new do
+       from 'me@test.lindsaar.net'
+         to 'you@test.lindsaar.net'
+    subject 'Here is the image you wanted'
+       body File.read('body.txt')
+   add_file {:filename => 'somefile.png', :content => File.read('/somefile.png')}
+ end
+ 
+ mail.deliver!
+
+Sending via sendmail can be done like so:
+
+  mail = Mail.new do
+        from 'me@test.lindsaar.net'
+          to 'you@test.lindsaar.net'
+     subject 'Here is the image you wanted'
+        body File.read('body.txt')
+    add_file {:filename => 'somefile.png', :content => File.read('/somefile.png')}
+  end
+  
+  mail.delivery_method :sendmail
+  
+  mail.deliver
+
+mail.deliver!
+
+
+=== Getting emails from a pop server:
+
+The most recent email:
+
+ require 'mail'
+ 
+ Mail.defaults do
+   pop3 'mail.myhost.com.au', 110 do
+     user 'mikel'
+     pass 'mypass'
+   end
+ end
+ 
+ emails = Mail.last do |email|
+   email.reply!("I'll be back on Monday, please be patient!") # +reply!+ still not implemented ^^
+ end
+
+The 3 oldest emails sorted by date in descendent order:
+
+ require 'mail'
+
+ Mail.defaults do
+   pop3 'mail.myhost.co.jp', 995 do
+     user 'mikel'
+     pass 'mypass'
+     enable_tls
+   end
+ end
+
+ emails = Mail.first(:count => 3, :order => :desc) do |email|
+   email.date
+ end
+
+Or even all emails:
+
+ require 'mail'
+
+ Mail.defaults do
+   pop3 'mail.myhost.com.au' do
+     user 'mikel'
+     pass 'mypass'
+   end
+ end
+
+ emails = Mail.all
+
+ emails.length #=> 12
+
+=== Reading an Email
+
+ require 'mail'
+ 
+ mail = Mail.read('/path/to/message.eml')
+ 
+ mail.envelope.from   #=> 'mikel@test.lindsaar.net'
+ mail.from.addresses  #=> ['mikel@test.lindsaar.net', 'ada@test.lindsaar.net']
+ mail.sender.address  #=> 'mikel@test.lindsaar.net'
+ mail.to              #=> 'bob@test.lindsaar.net'
+ mail.cc              #=> 'sam@test.lindsaar.net'
+ mail.subject         #=> "This is the subject"
+ mail.date.to_s       #=> '21 Nov 1997 09:55:06 -0600'
+ mail.message_id      #=> '<4D6AA7EB.6490534@xxx.xxx>'
+ mail.body.decoded    #=> 'This is the body of the email...
+
+Many more methods available.
+
+=== Reading a Multipart Email
+
+ require 'mail'
+ 
+ mail = Mail.read('multipart_email')
+ 
+ mail.multipart?          #=> true
+ mail.parts.length        #=> 2
+ mail.preamble            #=> "Text before the first part"
+ mail.epilogue            #=> "Text after the last part"
+ mail.parts.map { |p| p.content_type }  #=> ['text/plain', 'application/pdf']
+ mail.parts.map { |p| p.class }         #=> [Mail::Message, Mail::Message]
+ mail.parts[0].content_type_parameters  #=> {'charset' => 'ISO-8859-1'}
+ mail.parts[1].content_type_parameters  #=> {'name' => 'my.pdf'}
+
+Mail generates a tree of parts.  Each message has many or no parts.  Each part
+is another message which can have many or no parts.
+
+A message will only have parts if it is a multipart/mixed or related/mixed
+content type and has a boundary defined.
+
+=== Writing and sending a multipart/alternative (html and text) email
+
+Mail makes some basic assumptions and makes doing the common thing as 
+simple as possible.... (asking a lot from a mail library)
+
+ require 'mail'
+
+ mail = Mail.deliver do
+   to 'nicolas@test.lindsaar.net.au'
+   from 'Mikel Lindsaar <mikel@test.lindsaar.net.au>'
+   subject 'First multipart email sent with Mail'
+   text_part do
+     body 'This is plain text'
+   end
+   html_part do
+     content_type 'text/html; charset=UTF-8'
+     body '<h1>This is HTML</h1>'
+   end
+ end
+ 
+Mail then delivers the email at the end of the block and returns the
+resulting Mail::Message object, which you can then inspect if you
+so desire...
+
+ puts mail.to_s #=>
+
+ To: nicolas@test.lindsaar.net.au
+ From: Mikel Lindsaar <mikel@test.lindsaar.net.au>
+ Subject: First multipart email sent with Mail
+ Content-Type: multipart/alternative;
+   boundary=--==_mimepart_4a914f0c911be_6f0f1ab8026659
+ Message-ID: <4a914f12ac7e_6f0f1ab80267d1@baci.local.mail>
+ Date: Mon, 24 Aug 2009 00:15:46 +1000
+ Mime-Version: 1.0
+ Content-Transfer-Encoding: 7bit
+
+
+ ----==_mimepart_4a914f0c911be_6f0f1ab8026659
+ Content-ID: <4a914f12c8c4_6f0f1ab80268d6@baci.local.mail>
+ Date: Mon, 24 Aug 2009 00:15:46 +1000
+ Mime-Version: 1.0
+ Content-Type: text/plain
+ Content-Transfer-Encoding: 7bit
+
+ This is plain text
+ ----==_mimepart_4a914f0c911be_6f0f1ab8026659
+ Content-Type: text/html; charset=UTF-8
+ Content-ID: <4a914f12cf86_6f0f1ab802692c@baci.local.mail>
+ Date: Mon, 24 Aug 2009 00:15:46 +1000
+ Mime-Version: 1.0
+ Content-Transfer-Encoding: 7bit
+
+ <h1>This is HTML</h1>
+ ----==_mimepart_4a914f0c911be_6f0f1ab8026659--
+
+Mail inserts the content transfer encoding, the mime version, 
+the content-id's and handles the content-type and boundary.
+
+Mail assumes that if your text in the body is only us-ascii, that your
+transfer encoding is 7bit and it is text/plain.  You can override this
+by explicitly declaring it.
+
+=== Making Multipart/Alternate, without a block
+
+You don't have to use a block with the text and html part included, you
+can just do it declaratively.  However, you need to add Mail::Parts to
+an email, not Mail::Messages.
+
+ require 'mail'
+ 
+ mail = Mail.new do
+   to 'nicolas@test.lindsaar.net.au'
+   from 'Mikel Lindsaar <mikel@test.lindsaar.net.au>'
+   subject 'First multipart email sent with Mail'
+ end
+
+ text_part = Mail::Part.new do
+   body 'This is plain text'
+ end
+ 
+ html_part = Mail::Part.new do
+   content_type 'text/html; charset=UTF-8'
+   body '<h1>This is HTML</h1>'
+ end
+ 
+ mail.text_part = text_part
+ mail.html_part = html_part
+
+Results in the same email as done using the block form
+
+=== Getting error reports from an email:
+
+ require 'mail'
+ 
+ @mail = Mail.read('/path/to/bounce_message.eml')
+ 
+ @mail.bounced?         #=> true
+ @mail.final_recipient  #=> rfc822;mikel@dont.exist.com
+ @mail.action           #=> failed
+ @mail.error_status     #=> 5.5.0
+ @mail.diagnostic_code  #=> smtp;550 Requested action not taken: mailbox unavailable 
+ @mail.retryable?       #=> false
+
+=== Attaching and Detaching Files
+
+  require 'mail'
+
+You can just read the file off an absolute path, Mail will try
+to guess the mime_type and will encode the file in Base64 for you.
+  
+  @mail = Mail.new
+  @mail.add_file("/path/to/file.jpg")
+  @mail.parts.first.attachment? #=> true
+  @mail.parts.first.content_transfer_encoding.to_s #=> 'base64'
+  @mail.attachments.first.mime_type #=> 'image/jpg'
+  @mail.attachments.first.filename #=> 'file.jpg'
+  @mail.attachments.first.decoded == File.read('/path/to/file.jpg') #=> true
+
+Or You can pass in file_data and give it a filename, again, mail
+will try and guess the mime_type for you.
+  
+  @mail = Mail.new
+  @mail.attachments['myfile.pdf'] = File.read('path/to/myfile.pdf')
+  @mail.parts.first.attachment? #=> true
+  @mail.attachments.first.mime_type #=> 'application/pdf'
+  @mail.attachments.first.decoded == File.read('path/to/myfile.pdf') #=> true
+
+You can also override the guessed mime type if you really know better
+than mail (this should be rarely needed)
+
+  @mail = Mail.new
+  file_data = File.read('path/to/myfile.pdf')
+  @mail.attachments['myfile.pdf'] = { :mime_type => 'application/x-pdf',
+                                      :content => File.read('path/to/myfile.pdf') }
+  @mail.parts.first.mime_type #=> 'application/x-pdf'
+
+Of course... Mail will round trip an attachment as well
+
+  @mail = Mail.new do
+    to 'nicolas@test.lindsaar.net.au'
+    from 'Mikel Lindsaar <mikel@test.lindsaar.net.au>'
+    subject 'First multipart email sent with Mail'
+    text_part do
+      body 'Here is the attachment you wanted'
+    end
+    html_part do
+      content_type 'text/html; charset=UTF-8'
+      body '<h1>Funky Title</h1><p>Here is the attachment you wanted</p>'
+    end
+    add_file '/path/to/myfile.pdf'
+  end
+
+  @round_tripped_mail = Mail.new(@mail.encoded)
+  
+  @round_tripped_mail.attachments.length #=> 1
+  @round_tripped_mail.attachments.first.filename #=> 'myfile.pdf'
+
+== Using Mail with Testing or Spec'ing Libraries
+
+If mail is part of your system, you'll need a way to test it without actually
+sending emails, the TestMailer can do this for you.
+
+  require 'mail'
+  => true
+  Mail.defaults do
+    delivery_method :test
+  end
+  => #<Mail::Configuration:0x19345a8 @delivery_method=Mail::TestMailer>
+  Mail.deliveries
+  => []
+  Mail.deliver do
+    to 'mikel@me.com'
+    from 'you@you.com'
+    subject 'testing'
+    body 'hello'
+  end
+  => #<Mail::Message:0x19284ec ...
+  Mail.deliveries.length
+  => 1
+  Mail.deliveries.first
+  => #<Mail::Message:0x19284ec ...
+  Mail.deliveries.clear
+  => []
+
+== Excerpts from TREC Spam Corpus 2005
+
+The spec fixture files in spec/fixtures/emails/from_trec_2005 are from the 
+2005 TREC Public Spam Corpus. They remain copyrighted under the terms of
+that project and license agreement. They are used in this project to verify 
+and describe the development of this email parser implementation.
+
+http://plg.uwaterloo.ca/~gvcormac/treccorpus/
+
+They are used as allowed by 'Permitted Uses, Clause 3':
+
+    "Small excerpts of the information may be displayed to others
+     or published in a scientific or technical context, solely for
+     the purpose of describing the research and development and
+     related issues."
+     
+     -- http://plg.uwaterloo.ca/~gvcormac/treccorpus/
+
+== License:
+
+(The MIT License)
+
+Copyright (c) 2009
+
+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.