mail 1.0.0

data/.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+coverage
+rdoc
+gems

data/Manifest.txt

@@ -0,0 +1,106 @@
+.gitignore
+Manifest.txt
+README.rdoc
+Rakefile
+lib/mail.rb
+lib/mail/attachment.rb
+lib/mail/body.rb
+lib/mail/configuration.rb
+lib/mail/core_extensions/blank.rb
+lib/mail/core_extensions/nil.rb
+lib/mail/core_extensions/string.rb
+lib/mail/core_extensions.rb
+lib/mail/elements/address.rb
+lib/mail/elements/address_list.rb
+lib/mail/elements/content_disposition_element.rb
+lib/mail/elements/content_transfer_encoding_element.rb
+lib/mail/elements/content_type_element.rb
+lib/mail/elements/date_time_element.rb
+lib/mail/elements/envelope_from_element.rb
+lib/mail/elements/message_ids_element.rb
+lib/mail/elements/mime_version_element.rb
+lib/mail/elements/phrase_list.rb
+lib/mail/elements/received_element.rb
+lib/mail/encodings/base64.rb
+lib/mail/encodings/encodings.rb
+lib/mail/encodings/quoted_printable.rb
+lib/mail/envelope.rb
+lib/mail/field.rb
+lib/mail/field_list.rb
+lib/mail/fields/bcc_field.rb
+lib/mail/fields/cc_field.rb
+lib/mail/fields/comments_field.rb
+lib/mail/fields/common/common_address.rb
+lib/mail/fields/common/common_date.rb
+lib/mail/fields/common/common_field.rb
+lib/mail/fields/common/common_message_id.rb
+lib/mail/fields/content_description_field.rb
+lib/mail/fields/content_disposition_field.rb
+lib/mail/fields/content_id_field.rb
+lib/mail/fields/content_transfer_encoding_field.rb
+lib/mail/fields/content_type_field.rb
+lib/mail/fields/date_field.rb
+lib/mail/fields/from_field.rb
+lib/mail/fields/in_reply_to_field.rb
+lib/mail/fields/keywords_field.rb
+lib/mail/fields/message_id_field.rb
+lib/mail/fields/mime_version_field.rb
+lib/mail/fields/optional_field.rb
+lib/mail/fields/received_field.rb
+lib/mail/fields/references_field.rb
+lib/mail/fields/reply_to_field.rb
+lib/mail/fields/resent_bcc_field.rb
+lib/mail/fields/resent_cc_field.rb
+lib/mail/fields/resent_date_field.rb
+lib/mail/fields/resent_from_field.rb
+lib/mail/fields/resent_message_id_field.rb
+lib/mail/fields/resent_sender_field.rb
+lib/mail/fields/resent_to_field.rb
+lib/mail/fields/return_path_field.rb
+lib/mail/fields/sender_field.rb
+lib/mail/fields/structured_field.rb
+lib/mail/fields/subject_field.rb
+lib/mail/fields/to_field.rb
+lib/mail/fields/unstructured_field.rb
+lib/mail/header.rb
+lib/mail/mail.rb
+lib/mail/message.rb
+lib/mail/network/deliverable.rb
+lib/mail/network/retrievable.rb
+lib/mail/parsers/address_lists.rb
+lib/mail/parsers/address_lists.treetop
+lib/mail/parsers/content_disposition.rb
+lib/mail/parsers/content_disposition.treetop
+lib/mail/parsers/content_transfer_encoding.rb
+lib/mail/parsers/content_transfer_encoding.treetop
+lib/mail/parsers/content_type.rb
+lib/mail/parsers/content_type.treetop
+lib/mail/parsers/date_time.rb
+lib/mail/parsers/date_time.treetop
+lib/mail/parsers/envelope_from.rb
+lib/mail/parsers/envelope_from.treetop
+lib/mail/parsers/message_ids.rb
+lib/mail/parsers/message_ids.treetop
+lib/mail/parsers/mime_version.rb
+lib/mail/parsers/mime_version.treetop
+lib/mail/parsers/phrase_lists.rb
+lib/mail/parsers/phrase_lists.treetop
+lib/mail/parsers/received.rb
+lib/mail/parsers/received.treetop
+lib/mail/parsers/rfc2045.rb
+lib/mail/parsers/rfc2045.treetop
+lib/mail/parsers/rfc2822.rb
+lib/mail/parsers/rfc2822.treetop
+lib/mail/parsers/rfc2822_obsolete.rb
+lib/mail/parsers/rfc2822_obsolete.treetop
+lib/mail/part.rb
+lib/mail/patterns.rb
+lib/mail/utilities.rb
+lib/mail/version.rb
+lib/mail/version_specific/ruby_1_8.rb
+lib/mail/version_specific/ruby_1_8_string.rb
+lib/mail/version_specific/ruby_1_9.rb
+lib/mail/version_specific/multibyte.rb
+lib/mail/version_specific/multibyte/chars.rb
+lib/mail/version_specific/multibyte/exceptions.rb
+lib/mail/version_specific/multibyte/unicode_database.rb

data/README.rdoc

@@ -0,0 +1,441 @@
+= 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.
+
+== 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:
+
+* Add multilingual MIME support for mixed ASCII and multibyte headers
+* 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
+
+Right now Mail is still under development for a 1.0.0 release.
+
+The API will change between now and 1.0.0.  How much?  Not sure.  Basically though
+once 1.0.0 is released, no API removals within a single point release.  All removals
+to be depreciated with warnings for at least one point release before removal.
+
+Also, all private or protected methods to be declared as such.
+
+== 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.0.0.gem
+ 
+== 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:
+
+ require 'mail'
+
+ Mail.defaults do
+   smtp '127.0.0.1', 25
+ end
+
+ 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 'New Header Image', '/somefile.png'
+ end
+
+or
+ 
+ Mail.defaults do
+   smtp '127.0.0.1' # Port 25 defult
+ end
+
+ 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 'New Header Image', '/somefile.png'
+ end
+ 
+ mail.deliver!
+
+=== Getting an email from a pop server:
+
+ require 'mail'
+ 
+ Mail.defaults do
+   pop3 'mail.myhost.com.au', 110
+   user 'mikel'
+   pass 'mypass'
+ end
+ 
+ emails = Mail.get_all_mail
+ 
+ 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.addresses    #=> ['bob@test.lindsaar.net']
+ mail.cc.addresses    #=> ['sam@test.lindsaar.net']
+ mail.subject.to_s    #=> "This is the subject"
+ mail.date.to_s       #=> '21 Nov 1997 09:55:06 -0600'
+ mail.message_id      #=> '<4D6AA7EB.6490534@xxx.xxx>'
+ mail.body            #=> '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].mime_parameters          #=> {'charset' => 'ISO-8859-1'}
+ mail.parts[1].mime_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.defaults do
+   smtp '127.0.0.1' # Port 25 defult
+ end
+
+ 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(:filename => "/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
+  file_data = File.read('path/to/myfile.pdf')
+  @mail.add_file(:filename => 'myfile.pdf', :data => file_data)
+  @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.add_file(:filename => 'myfile.pdf', 
+                 :data => file_data,
+                 :mime_type => 'application/x-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 :filename => '/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'
+
+== 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.