In Files

Namespace

Class Index [+]

Quicksearch

Mail

encoding: utf-8

Comments Field

The Comments field inherits from UnstructuredField and handles the Comments: header field in the email.

Sending comments to a mail message will instantiate a Mail::Field object that has a CommentsField as it’s field type.

 

An email header can have as many comments fields as it wants. There is no upper limit, the comments field is also optional (that is, no comment is needed)

Examples:

 mail = Mail.new
 mail.comments = 'This is a comment'
 mail.comments    #=> 'This is a comment'
 mail[:comments]  #=> '#<Mail::Field:0x180e5e8 @field=#<Mail::CommentsField:0x180e1c4
 mail['comments'] #=> '#<Mail::Field:0x180e5e8 @field=#<Mail::CommentsField:0x180e1c4
 mail['comments'] #=> '#<Mail::Field:0x180e5e8 @field=#<Mail::CommentsField:0x180e1c4

 mail.comments = "This is another comment"
 mail[:comments].map { |c| c.to_s } 
 #=> ['This is a comment', "This is another comment"]

encoding: utf-8

trace = [return]

                        1*received

return = “Return-Path:” path CRLF

path = ([CFWS] “<” ([CFWS] / addr-spec) “>” [CFWS]) /

                        obs-path

received = “Received:” name-val-list “;” date-time CRLF

name-val-list = [CFWS] [name-val-pair *(CFWS name-val-pair)]

name-val-pair = item-name CFWS item-value

item-name = ALPHA *([“-”] (ALPHA / DIGIT))

item-value = 1*angle-addr / addr-spec /

                         atom / domain / msg-id

encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8

subject = “Subject:” unstructured CRLF


encoding: utf-8

keywords = “Keywords:” phrase *(“,” phrase) CRLF


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8

Mail Envelope

The Envelope class provides a field for the first line in an mbox file, that looks like “From mikel@test.lindsaar.net DATETIME“

This envelope class reads that line, and turns it into an Envelope.from and Envelope.date for your use.


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


Autogenerated from a Treetop grammar. Edits may be lost.


Autogenerated from a Treetop grammar. Edits may be lost.


Autogenerated from a Treetop grammar. Edits may be lost.


Autogenerated from a Treetop grammar. Edits may be lost.


Autogenerated from a Treetop grammar. Edits may be lost.


Autogenerated from a Treetop grammar. Edits may be lost.


Autogenerated from a Treetop grammar. Edits may be lost.


Autogenerated from a Treetop grammar. Edits may be lost.


Autogenerated from a Treetop grammar. Edits may be lost.


Autogenerated from a Treetop grammar. Edits may be lost.


Autogenerated from a Treetop grammar. Edits may be lost.


Autogenerated from a Treetop grammar. Edits may be lost.


Autogenerated from a Treetop grammar. Edits may be lost.


Autogenerated from a Treetop grammar. Edits may be lost.


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: us-ascii


encoding: utf-8


encoding: utf-8


encoding: utf-8


encoding: utf-8

Constants

RubyVer
RubyVer

Public Class Methods

all(*args, &block) click to toggle source

Receive all emails from a POP3 server. See Mail::POP3 for a complete documentation.

     # File lib/mail/mail.rb, line 164
164:   def Mail.all(*args, &block)
165:     retriever_method.all(*args, &block)
166:   end
defaults(&block) click to toggle source

Sets the default delivery method and retriever method for all new Mail objects. The delivery_method and retriever_method default to :smtp and :pop3, with defaults set.

So sending a new email, if you have an SMTP server running on localhost is as easy as:

  Mail.deliver do
    to      'mikel@test.lindsaar.net'
    from    'bob@test.lindsaar.net'
    subject 'hi there!'
    body    'this is a body'
  end

If you do not specify anything, you will get the following equivalent code set in every new mail object:

  Mail.defaults do
    delivery_method :smtp, { :address              => "localhost",
                             :port                 => 25,
                             :domain               => 'localhost.localdomain',
                             :user_name            => nil,
                             :password             => nil,
                             :authentication       => nil,
                             :enable_starttls_auto => true  }

    retriever_method :pop3, { :address             => "localhost",
                              :port                => 995,
                              :user_name           => nil,
                              :password            => nil,
                              :enable_ssl          => true }
  end

  Mail.delivery_method.new  #=> Mail::SMTP instance
  Mail.retriever_method.new #=> Mail::POP3 instance

Each mail object inherits the default set in Mail.delivery_method, however, on a per email basis, you can override the method:

  mail.delivery_method :sendmail

Or you can override the method and pass in settings:

  mail.delivery_method :sendmail, { :address => 'some.host' }

You can also just modify the settings:

  mail.delivery_settings = { :address => 'some.host' }

The passed in hash is just merged against the defaults with merge! and the result assigned the mail object. So the above example will change only the :address value of the global smtp_settings to be ‘some.host’, keeping all other values

     # File lib/mail/mail.rb, line 105
105:   def Mail.defaults(&block)
106:     Mail::Configuration.instance.instance_eval(&block)
107:   end
delete_all(*args, &block) click to toggle source

Delete all emails from a POP3 server. See Mail::POP3 for a complete documentation.

     # File lib/mail/mail.rb, line 175
175:   def Mail.delete_all(*args, &block)
176:     retriever_method.delete_all(*args, &block)
177:   end
deliver(*args, &block) click to toggle source

Send an email using the default configuration. You do need to set a default configuration first before you use Mail.deliver, if you don’t, an appropriate error will be raised telling you to.

If you do not specify a delivery type, SMTP will be used.

 Mail.deliver do
  to 'mikel@test.lindsaar.net'
  from 'ada@test.lindsaar.net'
  subject 'This is a test email'
  body 'Not much to say here'
 end

You can also do:

 mail = Mail.read('email.eml')
 mail.deliver!

And your email object will be created and sent.

     # File lib/mail/mail.rb, line 138
138:   def Mail.deliver(*args, &block)
139:     mail = Mail.new(args, &block)
140:     mail.deliver
141:     mail
142:   end
delivery_method() click to toggle source

Returns the delivery method selected, defaults to an instance of Mail::SMTP

     # File lib/mail/mail.rb, line 110
110:   def Mail.delivery_method
111:     Mail::Configuration.instance.delivery_method
112:   end
find(*args, &block) click to toggle source

Find emails in a POP3 server. See Mail::POP3 for a complete documentation.

     # File lib/mail/mail.rb, line 146
146:   def Mail.find(*args, &block)
147:     retriever_method.find(*args, &block)
148:   end
first(*args, &block) click to toggle source

Receive the first email(s) from a Pop3 server. See Mail::POP3 for a complete documentation.

     # File lib/mail/mail.rb, line 152
152:   def Mail.first(*args, &block)
153:     retriever_method.first(*args, &block)
154:   end
inform_interceptors(mail) click to toggle source
     # File lib/mail/mail.rb, line 214
214:   def Mail.inform_interceptors(mail)
215:     @@delivery_interceptors.each do |interceptor|
216:       interceptor.delivering_email(mail)
217:     end
218:   end
inform_observers(mail) click to toggle source
     # File lib/mail/mail.rb, line 208
208:   def Mail.inform_observers(mail)
209:     @@delivery_notification_observers.each do |observer|
210:       observer.delivered_email(mail)
211:     end
212:   end
last(*args, &block) click to toggle source

Receive the first email(s) from a Pop3 server. See Mail::POP3 for a complete documentation.

     # File lib/mail/mail.rb, line 158
158:   def Mail.last(*args, &block)
159:     retriever_method.last(*args, &block)
160:   end
new(*args, &block) click to toggle source

Allows you to create a new Mail::Message object.

You can make an email via passing a string or passing a block.

For example, the following two examples will create the same email message:

Creating via a string:

 string = 'To: mikel@test.lindsaar.net\r\n'
 string << 'From: bob@test.lindsaar.net\r\n\r\n'
 string << 'Subject: This is an email\r\n'
 string << '\r\n'
 string << 'This is the body'
 Mail.new(string)

Or creating via a block:

 message = Mail.new do
   to 'mikel@test.lindsaar.net'
   from 'bob@test.lindsaar.net'
   subject 'This is an email'
   body 'This is the body'
 end

Or creating via a hash (or hash like object):

 message = Mail.new({:to => 'mikel@test.lindsaar.net',
                     'from' => 'bob@test.lindsaar.net',
                      :subject 'This is an email',
                      :body 'This is the body' })

Note, the hash keys can be strings or symbols, the passed in object does not need to be a hash, it just needs to respond to :each_pair and yield each key value pair.

As a side note, you can also create a new email through creating a Mail::Message object directly and then passing in values via string, symbol or direct method calls. See Mail::Message for more information.

 mail = Mail.new
 mail.to = 'mikel@test.lindsaar.net'
 mail[:from] = 'bob@test.lindsaar.net'
 mail['subject'] = 'This is an email'
 mail.body = 'This is the body'
    # File lib/mail/mail.rb, line 49
49:   def Mail.new(*args, &block)
50:     Mail::Message.new(args, &block)
51:   end
read(filename) click to toggle source

Reads in an email message from a path and instantiates it as a new Mail::Message

     # File lib/mail/mail.rb, line 169
169:   def Mail.read(filename)
170:     Mail.new(File.read(filename))
171:   end
register_interceptor(interceptor) click to toggle source

You can register an object to be given every mail object that will be sent, before it is sent. So if you want to add special headers or modify any email that gets sent through the Mail library, you can do so.

Your object needs to respond to a single method # which receives the email that is about to be sent. Make your modifications directly to this object.

     # File lib/mail/mail.rb, line 202
202:   def Mail.register_interceptor(interceptor)
203:     unless @@delivery_interceptors.include?(interceptor)
204:       @@delivery_interceptors << interceptor
205:     end
206:   end
register_observer(observer) click to toggle source

You can register an object to be informed of every email that is sent through this method.

Your object needs to respond to a single method # which receives the email that is sent.

     # File lib/mail/mail.rb, line 189
189:   def Mail.register_observer(observer)
190:     unless @@delivery_notification_observers.include?(observer)
191:       @@delivery_notification_observers << observer
192:     end
193:   end
retriever_method() click to toggle source

Returns the retriever method selected, defaults to an instance of Mail::POP3

     # File lib/mail/mail.rb, line 115
115:   def Mail.retriever_method
116:     Mail::Configuration.instance.retriever_method
117:   end

Protected Class Methods

random_tag() click to toggle source
     # File lib/mail/mail.rb, line 222
222:   def Mail.random_tag
223:     t = Time.now
224:     sprintf('%x%x_%x%x%d%x',
225:             t.to_i, t.tv_usec,
226:             $$, Thread.current.object_id.abs, Mail.uniq, rand(255))
227:   end

Private Class Methods

something_random() click to toggle source
     # File lib/mail/mail.rb, line 231
231:   def Mail.something_random
232:     (Thread.current.object_id * rand(255) / Time.now.to_f).to_s.slice(3..1).to_i
233:   end
uniq() click to toggle source
     # File lib/mail/mail.rb, line 235
235:   def Mail.uniq
236:     @@uniq += 1
237:   end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.