module Mail
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
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 its 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"]
keywords = “Keywords:” phrase *(“,” phrase) CRLF
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
subject = “Subject:” unstructured CRLF
This is an almost cut and paste from ActiveSupport v3.0.6, copied in here so that Mail
itself does not depend on ActiveSupport to avoid versioning conflicts
line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/address_lists_machine.rb.rl”
line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/content_disposition_machine.rb.rl”
line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/content_location_machine.rb.rl”
line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/content_transfer_encoding_machine.rb.rl”
line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/content_type_machine.rb.rl”
line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/date_time_machine.rb.rl”
line 10 “/Users/raindrift/workspace/mail/lib/mail/parsers/ragel/ruby/machines/envelope_from_machine.rb.rl”
line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/message_ids_machine.rb.rl”
line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/mime_version_machine.rb.rl”
line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/phrase_lists_machine.rb.rl”
line 10 “/home/bpot/src/gh/bpot/mail/lib/mail/parsers/ragel/ruby/machines/received_machine.rb.rl”
Constants
- RANDOM_TAG
- RubyVer
Public Class Methods
Receive all emails from the default retriever See Mail::Retriever
for a complete documentation.
# File lib/mail/mail.rb, line 171 def self.all(*args, &block) retriever_method.all(*args, &block) end
# File lib/mail/mail.rb, line 191 def Mail.connection(&block) retriever_method.connection(&block) end
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 106 def self.defaults(&block) Configuration.instance.instance_eval(&block) end
Delete all emails from the default retriever See Mail::Retriever
for a complete documentation.
# File lib/mail/mail.rb, line 182 def self.delete_all(*args, &block) retriever_method.delete_all(*args, &block) end
Send an email using the default configuration. You do need to set a default configuration first before you use self.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 139 def self.deliver(*args, &block) mail = self.new(args, &block) mail.deliver mail end
Returns the delivery method selected, defaults to an instance of Mail::SMTP
# File lib/mail/mail.rb, line 111 def self.delivery_method Configuration.instance.delivery_method end
This runs through the autoload list and explictly requires them for you. Useful when running mail in a threaded process.
Usage:
require 'mail' Mail.eager_autoload!
# File lib/mail.rb, line 66 def self.eager_autoload! @@autoloads.each { |_,path| require(path) } end
Find emails from the default retriever See Mail::Retriever
for a complete documentation.
# File lib/mail/mail.rb, line 147 def self.find(*args, &block) retriever_method.find(*args, &block) end
Finds and then deletes retrieved emails from the default retriever See Mail::Retriever
for a complete documentation.
# File lib/mail/mail.rb, line 153 def self.find_and_delete(*args, &block) retriever_method.find_and_delete(*args, &block) end
Receive the first email(s) from the default retriever See Mail::Retriever
for a complete documentation.
# File lib/mail/mail.rb, line 159 def self.first(*args, &block) retriever_method.first(*args, &block) end
# File lib/mail/mail.rb, line 241 def self.inform_interceptors(mail) @@delivery_interceptors.each do |interceptor| interceptor.delivering_email(mail) end end
# File lib/mail/mail.rb, line 235 def self.inform_observers(mail) @@delivery_notification_observers.each do |observer| observer.delivered_email(mail) end end
Receive the first email(s) from the default retriever See Mail::Retriever
for a complete documentation.
# File lib/mail/mail.rb, line 165 def self.last(*args, &block) retriever_method.last(*args, &block) end
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" 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 50 def self.new(*args, &block) Message.new(args, &block) end
Reads in an email message from a path and instantiates it as a new Mail::Message
# File lib/mail/mail.rb, line 176 def self.read(filename) self.new(File.open(filename, 'rb') { |f| f.read }) end
Instantiates a new Mail::Message
using a string
# File lib/mail/mail.rb, line 187 def Mail.read_from_string(mail_as_string) Mail.new(mail_as_string) end
# File lib/mail.rb, line 54 def self.register_autoload(name, path) @@autoloads[name] = path autoload(name, path) end
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 delivering_email(mail) which receives the email that is about to be sent. Make your modifications directly to this object.
# File lib/mail/mail.rb, line 223 def self.register_interceptor(interceptor) unless @@delivery_interceptors.include?(interceptor) @@delivery_interceptors << interceptor end end
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 delivered_email(mail) which receives the email that is sent.
# File lib/mail/mail.rb, line 204 def self.register_observer(observer) unless @@delivery_notification_observers.include?(observer) @@delivery_notification_observers << observer end end
Returns the retriever method selected, defaults to an instance of Mail::POP3
# File lib/mail/mail.rb, line 116 def self.retriever_method Configuration.instance.retriever_method end
Unregister the given interceptor, allowing mail to resume operations without it.
# File lib/mail/mail.rb, line 231 def self.unregister_interceptor(interceptor) @@delivery_interceptors.delete(interceptor) end
Unregister the given observer, allowing mail to resume operations without it.
# File lib/mail/mail.rb, line 212 def self.unregister_observer(observer) @@delivery_notification_observers.delete(observer) end
Protected Class Methods
# File lib/mail/mail.rb, line 251 def self.random_tag t = Time.now sprintf(RANDOM_TAG, t.to_i, t.tv_usec, $$, Thread.current.object_id.abs, self.uniq, rand(255)) end
Private Class Methods
# File lib/mail/mail.rb, line 260 def self.something_random (Thread.current.object_id * rand(255) / Time.now.to_f).to_s.slice(-3..-1).to_i end
# File lib/mail/mail.rb, line 264 def self.uniq @@uniq += 1 end